The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
---
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)