Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

5.3 KB
Raw Blame
---
title: "Attributes"
sidebarTitle: "Overview"
description: "Describe the shared catalog with typed attributes, turn them into variant axes, and expose them as storefront filters."
---

Use attributes to give every product in your marketplace the same typed vocabulary, from sizes and materials to capacities and yes/no flags.

An attribute is a typed field that operators define once and attach to products in the shared master catalog. It describes products the same way across every store, feeds storefront filters, and, when it’s a variant axis, decides which variants a product can have. The Product Attribute module holds the attributes and their values. Links connect them to Medusa’s products, categories, and product options, so a variant axis is a real Medusa `ProductOption` underneath.

<img className="block dark:hidden" src="/images/figures/attribute-overview-light.svg" alt="The global attribute catalog lists Size, Material, Thread count, Gift wrap, and Care with their types, and Size is the one variant axis, backed by the global Medusa product option Size behind it." />
<img className="hidden dark:block" src="/images/figures/attribute-overview-dark.svg" alt="The global attribute catalog lists Size, Material, Thread count, Gift wrap, and Care with their types, and Size is the one variant axis, backed by the global Medusa product option Size behind it." />

<Note>
  The data models are `ProductAttribute` (id prefix `pattr`) and `ProductAttributeValue` (id prefix `pattrval`), resolved with `MercurModules.PRODUCT_ATTRIBUTE` from `@mercurjs/types`. Attributes belong to the catalog, never to a store.
</Note>

## Key features

The Product Attribute module covers the full life of a catalog attribute:

- **Five types**: `single_select`, `multi_select`, `text`, `unit`, and `toggle`, each storing its values differently
- **Variant axes**: a `multi_select` attribute with `is_variant_axis` creates a Medusa `ProductOption` that variants bind to
- **Global or inline**: define an attribute once for the whole catalog, or create a one-off attribute on a single product
- **Category scoping**: link an attribute to product categories so it’s offered only for products in them
- **Storefront filters**: shoppers filter products by axis values, and `is_filterable` tells your storefront which attributes to show as facets
- **One batch workflow**: attach, detach, and update all of a product’s attributes in a single run
- **Hooks and events**: catalog workflows expose hooks and emit `product-attribute.*` and `product-attribute-value.*` events

## How it works

An attribute reaches a product in four steps:

1. An operator runs `createProductAttributesWorkflow`. For a variant axis, it also creates a global `ProductOption` with the same values.
2. A product is created with Mercur’s `createProductsWorkflow`, or edited with `createAndLinkProductAttributesToProductWorkflow`, and picks the attributes and values it uses.
3. Selected values link to the product. For an axis, the product also gets the option with only the selected subset of values.
4. Variants bind to the axis option by its title, for example `{ Size: "M" }`, and the storefront filters products by those option values.

## Get started

Learn how attributes, values, and axes fit together.

<CardGroup cols={2}>
  <Card title="Attribute types" icon="shapes" href="/platform/attribute/concepts/attribute-types">
    The five types and how each one stores its values.
  </Card>
  <Card title="Variant axes" icon="sitemap" href="/platform/attribute/concepts/variant-axes">
    How an axis attribute mirrors a Medusa `ProductOption`.
  </Card>
  <Card title="Global vs inline" icon="layer-group" href="/platform/attribute/concepts/global-vs-inline">
    Catalog attributes, product-scoped attributes, categories, and filters.
  </Card>
</CardGroup>

## Examples

Build against attributes in your own server code.

<CardGroup cols={2}>
  <Card title="Create an attribute" icon="plus" href="/platform/attribute/guides/create-an-attribute">
    Run `createProductAttributesWorkflow` from a route or seed script.
  </Card>
  <Card title="Attach to a product" icon="link" href="/platform/attribute/guides/attach-attributes-to-a-product">
    Attach, detach, and update a product’s attributes in one run.
  </Card>
  <Card title="Create a variant axis" icon="sitemap" href="/platform/attribute/guides/create-a-variant-axis">
    Create an axis and build a product’s variants on it.
  </Card>
</CardGroup>

## Resources

The data models, links, workflows, service methods, and events behind attributes.

<CardGroup cols={2}>
  <Card title="Data models" icon="table" href="/platform/attribute/reference/data-models">
    `ProductAttribute` and `ProductAttributeValue`, field by field.
  </Card>
  <Card title="Links" icon="link" href="/platform/attribute/reference/links">
    Links to products, categories, and product options.
  </Card>
  <Card title="Workflows" icon="diagram-project" href="/platform/attribute/reference/workflows">
    Catalog workflows and product attachment workflows.
  </Card>
  <Card title="Service" icon="gear" href="/platform/attribute/reference/service">
    Module service methods for working with records directly.
  </Card>
  <Card title="Events" icon="bell" href="/platform/attribute/reference/events">
    Events emitted as attributes and values change.
  </Card>
</CardGroup>