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.

4.8 KB
Raw Blame
---
title: "Create a catalog attribute"
sidebarTitle: "Create an attribute"
description: "Create a global attribute with its values from a route, a seed script, or a catalog import."
---

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

<Steps>
  <Step title="Run createProductAttributesWorkflow from a route">
    The workflow takes a list of attributes, each with its values, and returns the created records.

    ```ts title="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.
  </Step>
  <Step title="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.

    ```ts
    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.
  </Step>
  <Step title="Add values later">
    Run `createProductAttributeValuesWorkflow` to add values to an existing select attribute. It takes one `attribute_id` and the new values.

    ```ts
    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`.
  </Step>
</Steps>

## 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.

```ts title="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

```ts
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.

## Next steps

- [Attach the attribute to a product](/platform/attribute/guides/attach-attributes-to-a-product)
- [Create a variant axis](/platform/attribute/guides/create-a-variant-axis)
- [Subscribe to attribute events](/platform/attribute/reference/events)