> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mercurjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach attributes to a product

> Attach, detach, and update a product's attributes in one run of the batch workflow.

Manage every attribute on a product from server code with one workflow, `createAndLinkProductAttributesToProductWorkflow`, the same engine behind the admin attribute batch route.

## Before you begin

You need the following:

* **A product**: the id of a product in the shared catalog, such as `prod_01JD8Q1234567`
* **Global attributes**: the ids of the catalog attributes and values you want to attach, created as in [Create a catalog attribute](https://docs.mercurjs.com/platform/attribute/guides/create-an-attribute.md)

## Run the batch workflow

**1. Send add, remove, and update in one input**

The workflow applies `remove`, then `add`, then `update`, so removing and re-adding the same attribute in one run works.

```ts title="src/api/admin/catalog-import/products/[id]/route.ts" theme={null}
import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import {
  createAndLinkProductAttributesToProductWorkflow,
} from "@mercurjs/core/workflows"

export async function POST(req: MedusaRequest, res: MedusaResponse) {
  await createAndLinkProductAttributesToProductWorkflow(req.scope).run({
    input: {
      product_id: req.params.id,
      add: [
        { id: "pattr_01JD8Q1234561", value_ids: ["pattrval_01JD8Q1234561"] },
        { id: "pattr_01JD8Q1234562", value: 400 },
        { title: "Gift wrap", value: true },
      ],
      remove: ["pattr_01JD8Q1234563"],
    },
  })

  res.sendStatus(200)
}
```

The first entry picks a value of a select attribute, the second sets a `unit` attribute to `400`, and the third creates an inline `toggle` attribute on this product.

**2. Read the attributes back**

A product holds its selections as linked values. Read them through the `product_attribute_values` link, and read inline attributes through `scoped_attributes`.

```ts theme={null}
const query = req.scope.resolve("query")

const { data: [product] } = await query.graph({
  entity: "product",
  fields: [
    "product_attribute_values.name",
    "product_attribute_values.attribute.name",
    "scoped_attributes.name",
  ],
  filters: { id: req.params.id },
})
```

Inline attributes also show up under `product_attribute_values`, because their values link to the product the same way.

## Choose the add form

Each `add` entry is a `ProductAttributeBatchAdd`. The keys you pass decide what the workflow does:

| Form | Shape | Effect |
| - | - | - |
| Existing select | `{ id, value_ids }` | Links the chosen values to the product |
| Existing axis | `{ id, value_ids }` | Attaches the global option with only those values, and links the values |
| Existing text or unit | `{ id, value }` | Creates a value named `String(value)` and links it |
| Existing toggle | `{ id, value }` | Links the seeded `"true"` or `"false"` value |
| Inline attribute | `{ title, type?, value }` or `{ title, type?, values }` | Creates a product-scoped attribute and its values, and links them |
| Inline axis | `{ title, values, is_variant_axis: true }` | Creates an exclusive option, a scoped `multi_select` attribute, and the mirrored values |

## Change a selection with update

An `update` entry targets one attribute by `id`. What `add` and `remove` mean depends on the attribute:

* **Global select or axis**: `add` and `remove` hold attribute value ids, and an axis also moves the option values
* **Global select or axis, full set**: `value_ids` is the complete set the product should hold, and the workflow works out the difference
* **Inline axis**: `add` holds new values such as `{ value: "XL" }`, and `remove` holds attribute value ids to delete
* **Text, unit, or toggle**: `value` replaces the current value
* **Inline rename**: `title` renames an inline attribute, and it’s ignored for global ones

```ts theme={null}
update: [
  { id: "pattr_01JD8Q1234561", value_ids: ["pattrval_01JD8Q1234562"] },
  { id: "pattr_01JD8Q1234564", title: "Fit", add: [{ value: "Relaxed" }] },
]
```

The first entry swaps the product to a different value. The second renames an inline axis and adds a value to its exclusive option.

## Handle a required attribute

Removing an attribute with `is_required: true` fails with a `NOT_ALLOWED` error, and nothing in the run is applied. The check skips attributes you remove and re-add in the same run, so you can replace a required attribute’s selection in one call.

## Route vendor edits through review

Running the batch workflow writes to the product immediately. For changes a store makes, run `productEditUpdateAttributesWorkflow` with the same `add`, `remove`, and `update` plus `created_by`. It stages a product change for review, and the change runs the batch workflow when it’s confirmed. See [Product edits](https://docs.mercurjs.com/platform/product-edit/overview.md).

## Next steps

* [Create a variant axis and build variants on it](https://docs.mercurjs.com/platform/attribute/guides/create-a-variant-axis.md)
* [Every attachment workflow and its input](https://docs.mercurjs.com/platform/attribute/reference/workflows.md)
* [The links behind product attributes](https://docs.mercurjs.com/platform/attribute/reference/links.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.