@mercurjs/docs 2.3.8-canary.3 → 2.3.9-canary.1

package/content/platform/attribute/reference/events.mdx

@@ -1,22 +1,59 @@
 ---
-title: "Event reference"
+title: "Attribute events"
 sidebarTitle: "Events"
-description: "Events emitted by the Attribute domain, for subscribers and side effects."
+description: "Events the Product Attribute workflows emit, when they fire, and their payloads."
 ---
 
-The Attribute domain emits events as attributes and their values change.
-Subscribe to them to run side effects, such as reindexing storefront filters,
-syncing an external PIM, or kicking off follow-up workflows, instead of polling.
+The catalog workflows emit 6 events as attributes and values change. Subscribe to them to reindex storefront facets, sync an external product information system, or start your own workflows. The event names are exported as `ProductAttributeWorkflowEvents` and `ProductAttributeValueWorkflowEvents` from `@mercurjs/core/workflows`.
 
-```ts title="src/subscribers/attribute-created.ts"
+## Attribute events
+
+Each event fires once per attribute, with that attribute’s id as the payload.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `product-attribute.created` | `createProductAttributesWorkflow` creates attributes | `{ id }` |
+| `product-attribute.updated` | `updateProductAttributesWorkflow` updates attributes, including an inline rename from the batch workflow | `{ id }` |
+| `product-attribute.deleted` | `deleteProductAttributesWorkflow` deletes attributes, including inline attributes removed from their product | `{ id }` |
+
+## Value events
+
+Each event fires once per value, with that value’s id as the payload.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `product-attribute-value.created` | `createProductAttributeValuesWorkflow` creates values, including new values added to an inline axis | `{ id }` |
+| `product-attribute-value.updated` | `updateProductAttributeValuesWorkflow` updates values | `{ id }` |
+| `product-attribute-value.deleted` | `deleteProductAttributeValuesWorkflow` deletes values, including values removed from an inline axis | `{ id }` |
+
+## What doesn’t emit
+
+Some writes create or change records without a matching event:
+
+- **Values created with an attribute**: `createProductAttributesWorkflow` emits only `product-attribute.created`, not a value event per value
+- **Upserts**: `upsertProductAttributeValuesWorkflow` emits nothing
+- **Attaching and detaching**: linking values to a product, `text` and `unit` values created on attach, and option changes on a product emit no attribute events
+
+## Subscribe to an event
+
+A subscriber receives one event per attribute. Resolve `query` to load the record by id.
+
+```ts title="src/subscribers/product-attribute-created.ts"
 import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
 
-export default async function attributeCreatedHandler({
+export default async function productAttributeCreated({
   event,
   container,
 }: SubscriberArgs<{ id: string }>) {
-  const attributeId = event.data.id
-  // ...reindex filters, sync to an external system, etc.
+  const query = container.resolve(ContainerRegistrationKeys.QUERY)
+  const { data: [attribute] } = await query.graph({
+    entity: "product_attribute",
+    fields: ["id", "name", "type", "is_filterable", "values.name"],
+    filters: { id: event.data.id },
+  })
+
+  container.resolve("logger").info(`Index facet ${attribute.name}`)
 }
 
 export const config: SubscriberConfig = {
@@ -24,18 +61,4 @@ export const config: SubscriberConfig = {
 }
 ```
 
-## Attribute events
-
-| Event | Emitted when | Payload |
-| --- | --- | --- |
-| `product-attribute.created` | An attribute is created | `{ id }` |
-| `product-attribute.updated` | An attribute changes | `{ id }` |
-| `product-attribute.deleted` | An attribute is deleted | `{ id }` |
-
-## Value events
-
-| Event | Emitted when | Payload |
-| --- | --- | --- |
-| `product-attribute-value.created` | A value is created | `{ id }` |
-| `product-attribute-value.updated` | A value changes | `{ id }` |
-| `product-attribute-value.deleted` | A value is deleted | `{ id }` |
+The subscriber loads the new attribute with its values. Swap the log line for a call to your search index.

package/content/platform/attribute/reference/links.mdx

@@ -1,45 +1,116 @@
 ---
-title: "Links to other modules"
+title: "Attribute links"
 sidebarTitle: "Links"
-description: "How the Attribute (Product Attribute) domain links to products, categories, and options."
+description: "The five module links between the Product Attribute module and Medusa's Product module."
 ---
 
-Modules in Mercur never reference each other directly. They're connected through
-**module links**. The Product Attribute module links into Medusa's product module
-in several ways: to products, to categories, and, for variant axes, to product
-options through mirror links. Once a link is defined, you retrieve related records
-with `query.graph` using the link alias.
+The Product Attribute module never references Medusa’s Product module directly. Five module links in `packages/core/src/links` connect them: two that store data in pivot tables and three read-only links resolved from a foreign key on one side. Resolve `query` from the container to read across them.
 
 ```ts
-const { data: products } = await query.graph({
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+const query = container.resolve(ContainerRegistrationKeys.QUERY)
+```
+
+## Product to attribute value
+
+The values a product holds, for every attribute type. This is the link the attachment workflows write.
+
+| Property | Value |
+| --- | --- |
+| Sides | `Product` ↔ `ProductAttributeValue` |
+| Cardinality | Many-to-many |
+| Storage | Pivot table `product_attribute_value_link` |
+| Aliases | `product_attribute_values` on product, `products` on value |
+| Defined in | `product-attribute-value-pivot-link.ts` |
+
+```ts
+const { data: [product] } = await query.graph({
   entity: "product",
-  fields: ["id", "title", "scoped_attributes.*"],
+  fields: [
+    "product_attribute_values.name",
+    "product_attribute_values.attribute.name",
+  ],
+  filters: { id: "prod_01JD8Q1234567" },
 })
 ```
 
-## Products
+The query returns each linked value with its parent attribute, which is how you read a product’s full attribute selection.
 
-| Link | Table | Relationship |
-| --- | --- | --- |
-| **Product → attribute** (`scoped_attributes`) | None | Read-only; a product's inline (product-scoped) attributes, resolved from `ProductAttribute.product_id` |
-| **Product ↔ attribute value** | `product_attribute_value_link` | Many-to-many pivot; the values selected on a product |
+## Product to scoped attributes
 
-## Categories
+The inline attributes created on a product. The link is read-only and resolves `ProductAttribute.product_id` against `product.id`.
 
-| Link | Table | Relationship |
-| --- | --- | --- |
-| **Attribute ↔ category** (`categories`) | `product_category_attribute` | Many-to-many; the product categories an attribute is associated with |
+| Property | Value |
+| --- | --- |
+| Sides | `Product` → `ProductAttribute` |
+| Cardinality | One-to-many |
+| Storage | None, read-only |
+| Alias | `scoped_attributes` on product |
+| Defined in | `product-attribute-product-link.ts` |
 
-## Product options (mirror links)
+```ts
+const { data: [product] } = await query.graph({
+  entity: "product",
+  fields: ["scoped_attributes.name", "scoped_attributes.values.name"],
+  filters: { id: "prod_01JD8Q1234567" },
+})
+```
+
+## Attribute to category
 
-| Link | FK | Relationship |
-| --- | --- | --- |
-| **Attribute → option** | `ProductAttribute.product_option_id` | Read-only 1:1; the mirror `ProductOption` for a variant-axis attribute |
-| **Value → option value** | `ProductAttributeValue.product_option_value_id` | Read-only 1:1; the mirror `ProductOptionValue` for an axis value |
+The product categories a global attribute is offered for. An attribute with no category links is offered for every product.
+
+| Property | Value |
+| --- | --- |
+| Sides | `ProductAttribute` ↔ `ProductCategory` |
+| Cardinality | Many-to-many |
+| Storage | Pivot table `product_category_attribute` |
+| Aliases | `categories` on attribute, `product_attributes` on category |
+| Defined in | `product-attribute-category-link.ts` |
+
+```ts
+const { data: attributes } = await query.graph({
+  entity: "product_attribute",
+  fields: ["id", "name", "categories.id", "categories.name"],
+  filters: { product_id: null },
+})
+```
+
+`createProductAttributesWorkflow` writes these links from `category_ids`. Write more yourself with the link service, using the keys `product_attribute_id` and `product_category_id`.
+
+## Attribute to product option
+
+The Medusa `ProductOption` that backs a variant axis. The link is read-only and keyed on `ProductAttribute.product_option_id`.
+
+| Property | Value |
+| --- | --- |
+| Sides | `ProductAttribute` → `ProductOption` |
+| Cardinality | One-to-one |
+| Storage | None, read-only |
+| Defined in | `product-attribute-option-mirror-link.ts` |
+
+## Attribute value to option value
+
+The Medusa `ProductOptionValue` that backs one value of a variant axis. The link is read-only and keyed on `ProductAttributeValue.product_option_value_id`.
+
+| Property | Value |
+| --- | --- |
+| Sides | `ProductAttributeValue` → `ProductOptionValue` |
+| Cardinality | One-to-one |
+| Storage | None, read-only |
+| Defined in | `product-attribute-value-option-value-mirror-link.ts` |
+
+Core code reads the mirror through the foreign keys, not through these links. Do the same: read the ids from the attribute, then query the option.
+
+```ts
+const { data: [option] } = await query.graph({
+  entity: "product_option",
+  fields: ["id", "title", "is_exclusive", "values.id", "values.value"],
+  filters: { id: attribute.product_option_id },
+})
+```
 
 <Note>
-  The mirror links (Attribute → option, Value → option value) and the product
-  scope link (`scoped_attributes`) are **read-only**. They're resolved from the
-  FK on the owning record and can't be written through the link itself. The
-  workflows keep the mirror in sync when axis attributes and values change.
+  The workflows keep the mirror in step. Never write `product_option_id` or `product_option_value_id` yourself, or the attribute and its option will drift apart.
 </Note>

package/content/platform/attribute/reference/service.mdx

@@ -1,49 +1,88 @@
 ---
-title: "Service reference"
+title: "Product Attribute module service"
 sidebarTitle: "Service"
-description: "The Product Attribute module service, with methods for working with records directly."
+description: "Resolve the Product Attribute module service, and the generated and overridden methods it exposes."
 ---
 
-The Product Attribute module exposes a service you can resolve from the Medusa
-container to read and write records directly, without going through a workflow.
-Use it inside custom services, subscribers, or scheduled jobs.
+The Product Attribute module service reads and writes `ProductAttribute` and `ProductAttributeValue` records directly. Use it for reads in routes, subscribers, and scheduled jobs. For writes, prefer the [workflows](/platform/attribute/reference/workflows), because the service doesn’t emit events, update the mirror `ProductOption`, or link values to products.
 
-```ts
-import { MercurModules } from "@mercurjs/types"
+## Resolve the service
+
+Resolve the service from the container with `MercurModules.PRODUCT_ATTRIBUTE`, whose value is `"product_attribute"`.
+
+```ts title="src/api/admin/catalog-import/facets/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { AttributeType, MercurModules } from "@mercurjs/types"
+
+export async function GET(req: MedusaRequest, res: MedusaResponse) {
+  const attributeService = req.scope.resolve(MercurModules.PRODUCT_ATTRIBUTE)
 
-const attributeModuleService = container.resolve(
-  MercurModules.PRODUCT_ATTRIBUTE,
-)
+  const [attributes, count] =
+    await attributeService.listAndCountProductAttributes(
+      { is_filterable: true, product_id: null },
+      { relations: ["values"], order: { rank: "ASC" } }
+    )
 
-const [attributes, count] =
-  await attributeModuleService.listAndCountProductAttributes({
-    type: "single_select",
-  })
+  res.json({ attributes, count })
+}
 ```
 
+The route lists filterable global attributes in rank order, each with its values.
+
 ## Generated methods
 
-Each data model gets a standard set of auto-generated methods. For
-`ProductAttribute`:
+The service extends `MedusaService`, so each data model gets the standard methods. For `ProductAttribute`:
 
 | Method | Description |
 | --- | --- |
-| `createProductAttributes(data)` | Create one or more attributes |
-| `retrieveProductAttribute(id, config?)` | Retrieve an attribute by id |
-| `listProductAttributes(filters?, config?)` | List attributes matching filters |
-| `listAndCountProductAttributes(filters?, config?)` | List attributes with a total count |
-| `updateProductAttributes(data)` | Update one or more attributes |
-| `deleteProductAttributes(ids)` | Delete one or more attributes |
-
-The same set exists for `ProductAttributeValue`: `createProductAttributeValues`,
-`retrieveProductAttributeValue`, `listProductAttributeValues`,
-`listAndCountProductAttributeValues`, `updateProductAttributeValues`, and
-`deleteProductAttributeValues`.
+| `retrieveProductAttribute(id, config?)` | Retrieve one attribute by id |
+| `listProductAttributes(filters?, config?)` | List attributes. Overridden, see below |
+| `listAndCountProductAttributes(filters?, config?)` | List attributes with a total count. Overridden, see below |
+| `createProductAttributes(data)` | Create one or more attributes. Overridden, see below |
+| `updateProductAttributes(data)` | Update one or more attributes by id. Overridden, see below |
+| `deleteProductAttributes(ids)` | Hard-delete attributes and their values |
+| `softDeleteProductAttributes(ids)` | Soft-delete attributes and their values |
+| `restoreProductAttributes(ids)` | Restore soft-deleted attributes |
+
+`ProductAttributeValue` gets the same set: `retrieveProductAttributeValue`, `listProductAttributeValues`, `listAndCountProductAttributeValues`, `createProductAttributeValues`, `updateProductAttributeValues`, `deleteProductAttributeValues`, `softDeleteProductAttributeValues`, and `restoreProductAttributeValues`.
+
+## Overridden methods
+
+Five methods add behavior on top of the generated ones.
+
+### createProductAttributes
+
+```ts
+createProductAttributes(data: object | object[], sharedContext?: Context)
+```
+
+Derives a `handle` from `name` for any global attribute created without one. After creating, it seeds a `"true"` value (rank 0) and a `"false"` value (rank 1) for every `toggle` attribute. It doesn’t create any other values, so add them with `createProductAttributeValues`.
+
+### updateProductAttributes
+
+```ts
+updateProductAttributes(data: object | object[], sharedContext?: Context)
+```
+
+Throws `INVALID_DATA` when an update sets a `type` that differs from the attribute’s current type. Every other field passes through.
+
+### listProductAttributes and listAndCountProductAttributes
+
+```ts
+listProductAttributes(filters?, config?: FindConfig, sharedContext?: Context)
+listAndCountProductAttributes(filters?, config?, sharedContext?)
+```
+
+When `config.relations` or `config.select` asks for `values`, the service loads them in a separate query. Only `single_select`, `multi_select`, and `toggle` attributes get their values. `text` and `unit` attributes come back with `values: []`, because their values belong to individual products.
+
+### createProductAttributeValues
+
+```ts
+createProductAttributeValues(data: object | object[], sharedContext?: Context)
+```
+
+Derives a `handle` from `name` for values of global `single_select` and `multi_select` attributes. Values of inline attributes and of `text`, `unit`, and `toggle` attributes keep a `null` handle.
 
 <Warning>
-  Prefer [workflows](/platform/attribute/reference/workflows) for anything with
-  side effects, such as creating an axis attribute, attaching attributes to a
-  product, or keeping the mirror `ProductOption` in sync. The service writes records
-  directly and does **not** emit events, maintain the option mirror, or run
-  compensation.
+  Writing `product_option_id` or `product_option_value_id` through the service doesn’t create or change any Medusa option. Use `createProductAttributesWorkflow` and the value workflows so the mirror stays correct.
 </Warning>

package/content/platform/attribute/reference/workflows.mdx

@@ -1,45 +1,175 @@
 ---
-title: "Workflows"
+title: "Attribute workflows"
 sidebarTitle: "Workflows"
-description: "Attribute catalog and product-attachment workflows."
+description: "Every catalog and product attachment workflow in the Product Attribute domain, with inputs, hooks, and events."
 ---
 
-This reference lists the workflows for the Attribute domain. Import them from
-`@mercurjs/core/workflows` and run them against the Medusa container.
+The Product Attribute domain exports 11 workflows from `@mercurjs/core/workflows`: 7 that manage the catalog and 4 that attach attributes to products. Run each one with `workflow(container).run({ input })`. When a step fails, the steps that already ran undo their work through their compensation functions.
 
 ## Catalog workflows
 
-Manage the attribute catalog and its values.
+These workflows create, change, and delete attributes and values. They keep the mirror `ProductOption` of a variant axis in step.
 
-| Workflow | Input | Purpose |
+### createProductAttributesWorkflow
+
+Creates attributes and their values. For each `multi_select` attribute with `is_variant_axis`, it first creates a global `ProductOption` (`is_exclusive: false`) titled with the attribute name, then links the values to its option values. Id `create-product-attributes`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `attributes` | `(CreateProductAttributeDTO & { category_ids?: string[] })[]` | Attributes to create, each with optional `values` |
+| `additional_data` | `Record<string, unknown>` | Passed to the `productAttributesCreated` hook |
+
+- **Returns**: `ProductAttributeDTO[]`
+- **Hooks**: `validate` with `{ input }`, `productAttributesCreated` with `{ attributes, additional_data }`
+- **Events**: `product-attribute.created` per attribute
+
+### updateProductAttributesWorkflow
+
+Updates every attribute matching `selector`. When `update.name` is set, it also renames the mirror option of each axis attribute. Id `update-product-attributes`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `selector` | `Record<string, unknown>` | Filters for the attributes to update, such as `{ id }` |
+| `update` | `UpdateProductAttributeDTO` | Fields to set. Changing `type` throws |
+| `additional_data` | `Record<string, unknown>` | Passed to the `productAttributesUpdated` hook |
+
+- **Returns**: `ProductAttributeDTO[]`
+- **Hooks**: `validate` with `{ input }`, `productAttributesUpdated` with `{ attributes, additional_data }`
+- **Events**: `product-attribute.updated` per attribute
+
+### deleteProductAttributesWorkflow
+
+Soft-deletes attributes and their values, then deletes the mirror options of axis attributes. It throws `NOT_ALLOWED` if any value of an attribute is linked to a product. Id `delete-product-attributes`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `ids` | `string[]` | Attribute ids |
+| `additional_data` | `Record<string, unknown>` | Passed to the `productAttributesDeleted` hook |
+
+- **Returns**: nothing
+- **Hooks**: `validate` with `{ input }`, `productAttributesDeleted` with `{ ids, additional_data }`
+- **Events**: `product-attribute.deleted` per id
+
+### createProductAttributeValuesWorkflow
+
+Adds values to one attribute. For an axis, it first adds the names to the mirror option and stores each new option value’s id. Id `create-product-attribute-values`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `attribute_id` | `string` | The parent attribute |
+| `values` | `CreateProductAttributeValueDTO[]` | Values to create, each with at least a `name` |
+| `additional_data` | `Record<string, unknown>` | Passed to the `productAttributeValuesCreated` hook |
+
+- **Returns**: `ProductAttributeValueDTO[]`
+- **Hooks**: `validate` with `{ input }`, `productAttributeValuesCreated` with `{ values, additional_data }`
+- **Events**: `product-attribute-value.created` per value
+
+### updateProductAttributeValuesWorkflow
+
+Updates every value matching `selector`. When the values belong to exactly one axis attribute, it rewrites that option’s values from the attribute’s value names. Id `update-product-attribute-values`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `selector` | `Record<string, unknown>` | Filters for the values to update |
+| `update` | `UpdateProductAttributeValueDTO` | Fields to set |
+| `additional_data` | `Record<string, unknown>` | Passed to the `productAttributeValuesUpdated` hook |
+
+- **Returns**: `ProductAttributeValueDTO[]`
+- **Hooks**: `validate` with `{ input }`, `productAttributeValuesUpdated` with `{ values, additional_data }`
+- **Events**: `product-attribute-value.updated` per value
+
+### deleteProductAttributeValuesWorkflow
+
+Soft-deletes values. When they belong to exactly one axis attribute, it rewrites that option’s values from the remaining value names. Id `delete-product-attribute-values`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `ids` | `string[]` | Value ids |
+| `additional_data` | `Record<string, unknown>` | Passed to the `productAttributeValuesDeleted` hook |
+
+- **Returns**: nothing
+- **Hooks**: `validate` with `{ input }`, `productAttributeValuesDeleted` with `{ ids, additional_data }`
+- **Events**: `product-attribute-value.deleted` per id
+
+### upsertProductAttributeValuesWorkflow
+
+Creates values without an `id` and updates values with one, for a single attribute. For an axis, it adds any new names to the mirror option first. Id `upsert-product-attribute-values`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `attribute_id` | `string` | The parent attribute |
+| `values` | `UpsertProductAttributeValueDTO[]` | Values to create or update, matched by `id` |
+
+- **Returns**: `ProductAttributeValueDTO[]`, created values first
+- **Hooks**: none
+- **Events**: none
+
+## Product attachment workflows
+
+These workflows attach attributes to products, write the `product_attribute_value_link` pivot, and attach or detach axis options on the product. Their input types are `ProductAttributeBatchAdd` and `ProductAttributeBatchUpdate` from `@mercurjs/types`.
+
+### createAndLinkProductAttributesToProductWorkflow
+
+The batch engine. It runs the remove, add, and update workflows below in that order, skipping any list that’s empty. Id `create-and-link-product-attributes-to-product`.
+
+| Input | Type | Description |
 | --- | --- | --- |
-| `createProductAttributesWorkflow` | `{ attributes[], additional_data? }` | Create attributes (+ values, + mirror option for axes) |
-| `updateProductAttributesWorkflow` | `{ selector, update }` | Update attribute fields |
-| `deleteProductAttributesWorkflow` | `{ ids[] }` | Delete attributes (fails if still linked) |
-| `createProductAttributeValuesWorkflow` | `{ values[], additional_data? }` | Add values to attributes |
-| `updateProductAttributeValuesWorkflow` | `{ selector, update }` | Update values |
-| `deleteProductAttributeValuesWorkflow` | `{ ids[] }` | Delete values |
-| `upsertProductAttributeValuesWorkflow` | `{ attribute_id, values[] }` | Create or update an attribute's values in one call |
+| `product_id` | `string` | The product to change |
+| `add` | `ProductAttributeBatchAdd[]` | Attributes to attach, existing or inline |
+| `remove` | `string[]` | Attribute ids to detach |
+| `update` | `ProductAttributeBatchUpdate[]` | Selections to change |
+| `additional_data` | `Record<string, unknown>` | Passed to the `productAttributesLinked` hook |
 
-## Product-attachment workflows
+- **Returns**: nothing
+- **Hooks**: `validate` with `{ input }`, `productAttributesLinked` with `{ product_id, additional_data }`
+- **Events**: none of its own. Nested catalog workflows emit theirs
 
-Attach attributes to products in the shared master catalog.
+### addProductAttributesToProductWorkflow
 
-| Workflow | Input | Purpose |
+Attaches attributes. It creates inline attributes and their exclusive options, creates `text` and `unit` values, attaches axis options with the selected subset, and links every value to the product. Id `add-product-attributes-to-product`.
+
+| Input | Type | Description |
 | --- | --- | --- |
-| `createAndLinkProductAttributesToProductWorkflow` | `{ product_id, add?, remove?, update? }` | Batch engine: attach, detach, and update, applied remove → add → update |
-| `addProductAttributesToProductWorkflow` | `{ product_id, add[] }` | Attach attributes (existing or inline) to a product |
-| `removeProductAttributesFromProductWorkflow` | `{ product_id, ... }` | Detach attributes from a product |
-| `updateProductAttributesOnProductWorkflow` | `{ product_id, ... }` | Update a product's attribute selections |
+| `product_id` | `string` | The product to change |
+| `add` | `ProductAttributeBatchAdd[]` | Attributes to attach |
+
+The input can also be an array of `{ product_id, add }` objects to attach to several products in one run. It has no hooks and emits no events.
+
+### removeProductAttributesFromProductWorkflow
+
+Detaches attributes. It throws `NOT_ALLOWED` for a required attribute unless the id is also in `readd`. It then detaches global axis options, drops the value links, and deletes inline attributes through `deleteProductAttributesWorkflow`. Id `remove-product-attributes-from-product`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | The product to change |
+| `remove` | `string[]` | Attribute ids to detach |
+| `readd` | `string[]` | Ids removed and re-added in the same batch, skipped by the required check |
+
+### updateProductAttributesOnProductWorkflow
+
+Changes selections. It resolves `value_ids` into an add and remove delta, moves global axis option values, swaps `text`, `unit`, and `toggle` values, adds or deletes values of an inline axis, and renames inline attributes from `title`. Id `update-product-attributes-on-product`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | The product to change |
+| `update` | `ProductAttributeBatchUpdate[]` | Selections to change |
 
 <Note>
-  `createAndLinkProductAttributesToProductWorkflow` is the engine behind the
-  product attribute batch endpoint; it composes the three single-purpose
-  attachment workflows. See
-  [Attach attributes to a product](/platform/attribute/guides/attach-attributes-to-a-product).
+  Changes made by these workflows land on the product right away. To route a store’s attribute edits through review, run `productEditUpdateAttributesWorkflow` from the [Product edits](/platform/product-edit/overview) domain, which applies the batch engine once the change is confirmed.
 </Note>
 
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/attribute/reference/service). To run side effects
-when an attribute changes, see the
-[Event reference](/platform/attribute/reference/events).
+## Steps
+
+The domain also exports its steps for use in your own workflows:
+
+| Step | Id | Compensation |
+| --- | --- | --- |
+| `createProductAttributesStep` | `pa-create-product-attributes` | Deletes the created attributes |
+| `updateProductAttributesStep` | `pa-update-product-attributes` | Restores previous field values |
+| `deleteProductAttributesStep` | `pa-delete-product-attributes` | Restores the soft-deleted attributes |
+| `createProductAttributeValuesStep` | `pa-create-product-attribute-values` | Deletes the created values |
+| `updateProductAttributeValuesStep` | `pa-update-product-attribute-values` | Restores previous field values |
+| `deleteProductAttributeValuesStep` | `pa-delete-product-attribute-values` | Restores the soft-deleted values |
+| `detachProductOptionValuesFromProductStep` | `pa-detach-product-option-values-from-product` | Re-attaches the option values |
+| `validateProductAttributesNotLinkedStep` | `pa-validate-attributes-not-linked` | None |
+| `validateProductAttributesNotRequiredStep` | `pa-validate-attributes-not-required` | None |