Skip to main content
Product attributes extend the master catalog with structured, typed data — “Material: Cotton”, “Weight: 10kg”, “Waterproof: yes”. The operator defines the attribute catalog; products reference it. Attributes power filtering, enforce consistent values across sellers, and — for select attributes — can drive variant generation.

​
Attribute types

TypeValuesExample
multi_selectMultiple values from a defined listColor: Red, Blue, Green
single_selectOne value from a defined listCondition: New
textFree textCare instructions
unitA measured valueWeight: 10kg
toggleBoolean — fixed true / false valuesWaterproof

​
Attribute fields

FieldDescription
name / handleDisplay name and unique handle
typeOne of the types above
is_variant_axisWhether the attribute generates product variants — only allowed for multi_select
is_filterableWhether the attribute is exposed as a storefront filter
is_requiredWhether products must set a value
rankOrdering in listings and forms
is_activeSoft enable/disable
product_idnull for global attributes; set when the attribute is product-scoped
Each select attribute owns a ranked list of values (ProductAttributeValue), managed by the operator in the Admin Panel.

​
Global vs product-scoped

  • Global attributes (product_id = null) live in the marketplace-wide catalog. They can be attached to any product and linked to categories, so the right attributes surface for the right product types.
  • Product-scoped attributes are created inline from a single product’s form — a one-off axis or field that doesn’t belong in the shared catalog. They don’t appear in the global attribute list.

​
Variant axes and native product options

Attributes marked is_variant_axis are not a parallel system — a variant-axis attribute is backed by a native Medusa global product option. The attribute and its values mirror one-to-one onto a ProductOption and its option values:
  • A global axis attribute maps to a shared product option that many products link to, each restricted to its selected subset of values.
  • A product-scoped axis attribute maps to an exclusive, product-owned option.
Because axes are real product options, variants are built with Medusa’s standard machinery — variants[].options maps axis titles to value names, exactly as in a plain Medusa project. Non-axis attributes never become options; they attach as plain value links. Only multi_select attributes can be variant axes — an axis needs an enumerable set of values to combine into variants.

​
Attaching attributes to products

Products manage their attributes through a single batch endpoint that adds, removes, and updates in one request: 
curl -X POST "http://localhost:9000/vendor/products/prod_123/attributes/batch" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "add": [
      { "id": "pattr_material", "value_ids": ["pattrval_cotton"] },
      { "title": "Fit", "values": ["Slim", "Regular"], "is_variant_axis": true }
    ],
    "remove": ["pattr_old"]
  }'
An entry either references an existing attribute by id (with the selected value_ids, or a value for text/unit/toggle types) or defines an inline one by title — created product-scoped on the fly. At product create time, the same shape is passed as a unified attributes[] array.

​
Who manages what

SurfaceCapability
Admin PanelOwns the attribute catalog — create attributes, manage possible values, set ranking, edit flags
Vendor PortalConsumes attributes on products — select values, propose inline attributes as part of product submissions
Store APIReads attributes for display and filtering
Attribute changes on products submitted by vendors flow through the same change-request pipeline as other product edits.

​
Next steps

Products

The master catalog attributes describe.

Product Requests & Approvals

How attribute edits are reviewed.