Create a catalog attribute

Create global catalog attributes from your own server code, for example when you seed a marketplace or import a taxonomy from a product information system.

Before you begin

You need the following:

A Mercur server: an API app with @mercurjs/core registered through withMercur()
Workflow imports: every workflow on this page comes from @mercurjs/core/workflows

Create the attribute

Run createProductAttributesWorkflow from a route

The workflow takes a list of attributes, each with its values, and returns the created records.

src/api/admin/catalog-import/attributes/route.ts

import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { AttributeType } from "@mercurjs/types"
import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"

export async function POST(req: MedusaRequest, res: MedusaResponse) {
  const { result } = await createProductAttributesWorkflow(req.scope).run({
    input: {
      attributes: [
        {
          name: "Material",
          type: AttributeType.SINGLE_SELECT,
          is_filterable: true,
          values: [{ name: "Cotton" }, { name: "Linen" }],
        },
      ],
    },
  })

  res.status(201).json({ product_attributes: result })
}

Leaving out product_id makes the attribute global. The service derives the handle material and a handle for each value.

Scope it to categories

Pass category_ids to link the attribute to product categories in the same run. An attribute with no categories is offered for every product.

await createProductAttributesWorkflow(req.scope).run({
  input: {
    attributes: [
      {
        name: "Thread count",
        type: AttributeType.UNIT,
        category_ids: ["pcat_01JD8Q1234567"],
      },
    ],
  },
})

A unit attribute has no predefined values. Each product gets its own value when you attach the attribute.

Add values later

Run createProductAttributeValuesWorkflow to add values to an existing select attribute. It takes one attribute_id and the new values.

import { createProductAttributeValuesWorkflow } from "@mercurjs/core/workflows"

await createProductAttributeValuesWorkflow(req.scope).run({
  input: {
    attribute_id: "pattr_01JD8Q1234567",
    values: [{ name: "Wool" }, { name: "Silk", rank: 3 }],
  },
})

For a variant axis, the workflow also adds the values to the mirror ProductOption.

Attach custom data with additional_data

Every catalog workflow accepts additional_data and passes it to its completion hook. Register a handler on productAttributesCreated to store your own data next to the attribute without forking the workflow.

src/workflows/hooks/product-attributes-created.ts

import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"

createProductAttributesWorkflow.hooks.productAttributesCreated(
  async ({ attributes, additional_data }, { container }) => {
    const logger = container.resolve("logger")
    const source = additional_data?.imported_from

    for (const attribute of attributes) {
      logger.info(`Attribute ${attribute.id} imported from ${source}`)
    }
  }
)

Pass the data when you run the workflow, for example additional_data: { imported_from: "legacy_pim" }. The workflow also exposes a validate hook that runs before anything is written, so you can throw there to reject the input.

Update or delete an attribute

updateProductAttributesWorkflow takes a selector and an update. Keep these rules in mind:

Type is fixed: the service throws if update.type differs from the current type
Renames reach the option: changing name on an axis also renames its ProductOption
Deletes check usage: deleteProductAttributesWorkflow throws NOT_ALLOWED while any value is linked to a product

import { updateProductAttributesWorkflow } from "@mercurjs/core/workflows"

await updateProductAttributesWorkflow(req.scope).run({
  input: {
    selector: { id: "pattr_01JD8Q1234567" },
    update: { name: "Fabric", is_filterable: false },
  },
})

The run renames the attribute and turns off its facet flag. The handle stays material, because handles are derived only on create.

Store

Catalog

Offer

Attribute

Product Edit

Order Group

Commission

Payout

Review

Before you begin

Create the attribute

Attach custom data with additional_data

Update or delete an attribute

Next steps

​Before you begin

​Create the attribute

​Attach custom data with additional_data

​Update or delete an attribute

​Next steps

Before you begin

Create the attribute

Attach custom data with additional_data

Update or delete an attribute

Next steps