@mercurjs/docs 2.2.0-canary.40

package/content/references/workflows/order/create-order-fulfillment.mdx

@@ -0,0 +1,45 @@
+---
+title: "createOrderFulfillmentWorkflow"
+description: "Create a fulfillment for order items, offer-bundle aware."
+---
+
+Mercur's offer-aware replacement for Medusa's create-order-fulfillment flow. Validates the order and items, creates the fulfillment, registers it on the order, links it, and consumes reservations / adjusts inventory — multiplying quantities by each offer's `required_quantity` inventory links so bundle offers deduct the right stock. Triggered by `POST /vendor/orders/:id/fulfillments`. Emits `order.fulfillment_created`.
+
+## Usage
+
+```ts
+import { createOrderFulfillmentWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createOrderFulfillmentWorkflow(container).run({
+  input: {
+    order_id: "order_123",
+    items: [{ id: "ordli_123", quantity: 1 }],
+  },
+})
+```
+
+## Input
+
+<ParamField body="order_id" type="string" required>The order to fulfill.</ParamField>
+<ParamField body="items" type="{ id: string; quantity: number }[]" required>Order line items and quantities to fulfill; all items must either require shipping or not — mixed requests throw.</ParamField>
+<ParamField body="location_id" type="string">Stock location to fulfill from; defaults to the shipping option's linked location.</ParamField>
+<ParamField body="shipping_option_id" type="string">Shipping option to fulfill with; defaults to the order's first shipping method.</ParamField>
+<ParamField body="created_by" type="string">Id of the user creating the fulfillment.</ParamField>
+<ParamField body="labels" type="FulfillmentLabelDTO[]">Tracking labels to attach.</ParamField>
+<ParamField body="no_notification" type="boolean">Suppress customer notification for this fulfillment.</ParamField>
+<ParamField body="metadata" type="object | null">Custom key-value data on the fulfillment.</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="FulfillmentDTO">The created fulfillment.</ResponseField>
+
+## Hooks
+
+- `fulfillmentCreated` — runs after creation with `{ fulfillment, additional_data }`.
+
+```ts
+createOrderFulfillmentWorkflow.hooks.fulfillmentCreated(async ({ fulfillment }) => {
+  // push to a 3PL
+})
+```

package/content/references/workflows/order-group/get-order-group-detail.mdx

@@ -0,0 +1,29 @@
+---
+title: "getOrderGroupDetailWorkflow"
+description: "Retrieve one order group with per-order aggregated payment and fulfillment statuses."
+---
+
+Loads an order group with its child orders and computes each order's `payment_status` and `fulfillment_status` from its payment collections and fulfillments. Payment collections and fulfillments are stripped from the response unless the requested fields include them. Triggered by `GET /admin/order-groups/:id` and `GET /admin/orders/:id/order-group`.
+
+## Usage
+
+```ts
+import { getOrderGroupDetailWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await getOrderGroupDetailWorkflow(container).run({
+  input: {
+    order_group_id: "ordgrp_123",
+    fields: ["display_id", "total", "orders.display_id"],
+  },
+})
+```
+
+## Input
+
+<ParamField body="order_group_id" type="string" required>The order group to retrieve; fails if not found.</ParamField>
+<ParamField body="fields" type="string[]" required>Fields to retrieve; merged with the defaults needed for status aggregation (`orders.items.*`, payment collection and fulfillment timestamps).</ParamField>
+
+## Result
+
+<ResponseField name="result" type="object">The order group with its child orders.</ResponseField>
+<ResponseField name="result.orders" type="OrderDetailDTO[]">Child orders, each with computed `payment_status` and `fulfillment_status`.</ResponseField>

package/content/references/workflows/order-group/get-order-groups-list.mdx

@@ -0,0 +1,36 @@
+---
+title: "getOrderGroupsListWorkflow"
+description: "List order groups with pagination and per-order aggregated statuses."
+---
+
+Lists order groups with their child orders, computing each order's `payment_status` and `fulfillment_status` from payment collections and fulfillments. When `sellerId` is set, each group's `orders` array is filtered to that seller's orders — useful for vendor-scoped views. Payment collections and fulfillments are stripped unless the requested fields include them. Triggered by `GET /admin/order-groups`.
+
+## Usage
+
+```ts
+import { getOrderGroupsListWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await getOrderGroupsListWorkflow(container).run({
+  input: {
+    fields: ["display_id", "total"],
+    variables: { skip: 0, take: 20, order: { created_at: "DESC" } },
+  },
+})
+```
+
+## Input
+
+<ParamField body="fields" type="string[]" required>Fields to retrieve; merged with the defaults needed for status aggregation.</ParamField>
+<ParamField body="variables" type="object">Query filters plus pagination.
+  <Expandable title="properties">
+    <ParamField body="skip" type="number">Number of groups to skip.</ParamField>
+    <ParamField body="take" type="number">Number of groups to return.</ParamField>
+    <ParamField body="order" type="object">Sort spec, e.g. `{ created_at: "DESC" }`.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="sellerId" type="string | string[]">Restrict each group's `orders` to the given seller(s).</ParamField>
+
+## Result
+
+<ResponseField name="result.rows" type="object[]">The order groups; each child order carries computed `payment_status` and `fulfillment_status`.</ResponseField>
+<ResponseField name="result.metadata" type="object">Pagination metadata (`count`, `skip`, `take`).</ResponseField>

package/content/references/workflows/overview.mdx

@@ -0,0 +1,72 @@
+---
+title: "Workflows"
+description: "Every workflow exported by @mercurjs/core, grouped by domain."
+---
+
+All marketplace business logic runs through Medusa workflows exported from `@mercurjs/core/workflows`. Run them from your own API routes, jobs, or subscribers, and extend them through their hooks — see [Extend a workflow](/rc/resources/customization/extend-a-workflow).
+
+```ts
+import { createSellersWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createSellersWorkflow(container).run({
+  input: { name: "Acme", email: "hello@acme.co" },
+})
+```
+
+Each workflow has its own reference page with the exact input, result, and hooks.
+
+<CardGroup cols={2}>
+  <Card title="Seller lifecycle" href="/rc/references/workflows/seller/create-sellers">
+    Create, approve, suspend, terminate sellers and manage their details.
+  </Card>
+  <Card title="Members & invites" href="/rc/references/workflows/member/add-seller-member">
+    Team management and the JWT invite flow.
+  </Card>
+  <Card title="Checkout & carts" href="/rc/references/workflows/cart/complete-cart-with-split-orders">
+    The multi-vendor split checkout and per-seller cart operations.
+  </Card>
+  <Card title="Order groups" href="/rc/references/workflows/order-group/get-order-group-detail">
+    Read models over grouped per-seller orders.
+  </Card>
+  <Card title="Commission" href="/rc/references/workflows/commission/create-commission-rates">
+    Rate CRUD, rule batching, and order line recomputation.
+  </Card>
+  <Card title="Payout" href="/rc/references/workflows/payout/create-payout">
+    Accounts, onboarding, payouts, and webhook processing.
+  </Card>
+  <Card title="Products" href="/rc/references/workflows/product/create-products">
+    Master product creation, confirmation, and seller linking.
+  </Card>
+  <Card title="Product edit" href="/rc/references/workflows/product-edit/create-product-change">
+    The change-request lifecycle behind vendor edits.
+  </Card>
+  <Card title="Product attributes" href="/rc/references/workflows/product-attribute/create-and-link-product-attributes-to-product">
+    Attribute catalog CRUD and the product batch engine.
+  </Card>
+  <Card title="Offers" href="/rc/references/workflows/offer/create-offers">
+    Listing CRUD and inventory item batching.
+  </Card>
+  <Card title="Media" href="/rc/references/workflows/media/set-collection-images">
+    Category and collection galleries, thumbnails, banners, icons.
+  </Card>
+  <Card title="Orders & RMA" href="/rc/references/workflows/order/create-order-fulfillment">
+    Fulfillment and return/claim/exchange confirmation.
+  </Card>
+</CardGroup>
+
+## Internal and utility workflows
+
+These are exported but usually not called directly — they run inside the workflows above:
+
+| Workflow | Called by |
+| --- | --- |
+| `applyProductChangeActionsWorkflow` / `applyProductAttributeChangeActionsWorkflow` | `confirmProductChangeWorkflow` — replays staged actions onto the product |
+| `productEditUpdateProductWorkflow` / `productEditUpdateVariantsWorkflow` / `productEditUpdateAttributesWorkflow` / `productEditDeleteProductWorkflow` | Vendor product edit routes — stage the corresponding change actions |
+| `recordProductAuditChangeWorkflow` | Product flows — writes audit change records |
+| `create/update/deleteProductCategoryWithImagesWorkflow` and `create/update/deleteProductCollectionWithImagesWorkflow` | Admin category/collection routes — wrap Medusa's workflows plus the image-set step |
+| `createSellerCampaignsWorkflow`, `createSellerCustomerGroupsWorkflow`, `createSellerInventoryItemsWorkflow`, `createSellerPriceListsWorkflow`, `createSellerPromotionsWorkflow`, `createSellerShippingOptionsWorkflow`, `createSellerShippingProfilesWorkflow`, `createSellerStockLocationsWorkflow` | Vendor resource-create routes — create the record and link it to the seller |
+
+<Note>
+  Search has no workflows by design — index synchronization is event-driven
+  through subscribers. See the [Search module](/rc/references/modules/search#index-synchronization).
+</Note>

package/content/references/workflows/payout/create-onboarding.mdx

@@ -0,0 +1,36 @@
+---
+title: "createOnboardingWorkflow"
+description: "Start a provider onboarding session for a payout account."
+---
+
+Creates an onboarding session for an existing payout account through the payout provider — for Stripe Connect this returns a hosted onboarding link the seller completes in the browser. Triggered by `POST /vendor/payout-accounts/:id/onboarding`.
+
+## Usage
+
+```ts
+import { createOnboardingWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createOnboardingWorkflow(container).run({
+  input: {
+    account_id: "pacc_123",
+    data: {
+      refresh_url: "https://vendor.example.com/payouts",
+      return_url: "https://vendor.example.com/payouts",
+    },
+  },
+})
+```
+
+## Input
+
+<ParamField body="account_id" type="string" required>The payout account to onboard.</ParamField>
+<ParamField body="context" type="object">Provider context; supports `idempotency_key` plus provider-specific keys.</ParamField>
+<ParamField body="data" type="object">Provider-specific onboarding data (e.g. Stripe `refresh_url` / `return_url`).</ParamField>
+
+## Result
+
+<ResponseField name="result" type="OnboardingDTO">The created onboarding session.</ResponseField>
+<ResponseField name="result.id" type="string">Onboarding ID.</ResponseField>
+<ResponseField name="result.account_id" type="string">The payout account the session belongs to.</ResponseField>
+<ResponseField name="result.data" type="object | null">Provider response data (e.g. the hosted onboarding URL).</ResponseField>
+<ResponseField name="result.context" type="object | null">The context the session was created with.</ResponseField>

package/content/references/workflows/payout/create-payout-account.mdx

@@ -0,0 +1,33 @@
+---
+title: "createPayoutAccountWorkflow"
+description: "Create a payout account for a seller through the registered payout provider."
+---
+
+Validates that the seller doesn't already have a payout account, creates one through the payout provider (e.g. Stripe Connect), and links it to the seller. Triggered by `POST /vendor/payout-accounts`.
+
+## Usage
+
+```ts
+import { createPayoutAccountWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createPayoutAccountWorkflow(container).run({
+  input: {
+    seller_id: "sel_123",
+    context: { country: "US" },
+  },
+})
+```
+
+## Input
+
+<ParamField body="seller_id" type="string" required>The seller to create the payout account for; fails if the seller already has one.</ParamField>
+<ParamField body="context" type="object">Provider context; supports `idempotency_key` plus provider-specific keys.</ParamField>
+<ParamField body="data" type="object">Provider-specific creation data passed straight to the payout provider.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="PayoutAccountDTO">The created payout account.</ResponseField>
+<ResponseField name="result.id" type="string">Payout account ID.</ResponseField>
+<ResponseField name="result.status" type="string">One of `pending`, `active`, `restricted`, `rejected`; starts as `pending` until onboarding completes.</ResponseField>
+<ResponseField name="result.data" type="object">Provider-side account data (e.g. the connected account payload).</ResponseField>
+<ResponseField name="result.context" type="object | null">The context the account was created with.</ResponseField>

package/content/references/workflows/payout/create-payout.mdx

@@ -0,0 +1,30 @@
+---
+title: "createPayoutWorkflow"
+description: "Issue a payout to a seller through the registered provider."
+---
+
+Loads a settled order with its seller and payout account, sums the order's commission lines (item and shipping), and pays out `order.total - total commission` through the payout provider, linking the payout to the seller. Fails if the seller has no payout account. The order ID doubles as the provider idempotency key, so re-running for the same order is safe. Not wired to a route — run it from your own subscriber or scheduled job once an order is captured and ready to settle.
+
+## Usage
+
+```ts
+import { createPayoutWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createPayoutWorkflow(container).run({
+  input: { order_id: "order_123" },
+})
+```
+
+## Input
+
+<ParamField body="order_id" type="string" required>The order to settle; must belong to a seller with a payout account.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="PayoutDTO">The created payout.</ResponseField>
+<ResponseField name="result.id" type="string">Payout ID.</ResponseField>
+<ResponseField name="result.account_id" type="string">The seller's payout account.</ResponseField>
+<ResponseField name="result.amount" type="BigNumberInput">Order total minus the order's commission lines.</ResponseField>
+<ResponseField name="result.currency_code" type="string">The order's currency.</ResponseField>
+<ResponseField name="result.status" type="string">One of `pending`, `processing`, `paid`, `failed`, `canceled`.</ResponseField>
+<ResponseField name="result.data" type="object | null">Provider transfer data; includes `order_id` and `seller_id`.</ResponseField>

package/content/references/workflows/payout/process-payout-for-webhook.mdx

@@ -0,0 +1,32 @@
+---
+title: "processPayoutForWebhookWorkflow"
+description: "Apply a payout provider webhook event to the matching account or payout."
+---
+
+Maps a normalized provider webhook action to a status update: account events set the payout account to `active`, `restricted`, or `rejected`; payout events set the payout to `processing`, `paid`, `failed`, or `canceled`. Unsupported actions (or events without an ID) are ignored. Triggered by the `payout-webhook` subscriber after the payout provider parses the raw webhook payload.
+
+## Usage
+
+```ts
+import { processPayoutForWebhookWorkflow } from "@mercurjs/core/workflows"
+
+await processPayoutForWebhookWorkflow(container).run({
+  input: {
+    action: "payout.paid",
+    data: { id: "payout_123" },
+  },
+})
+```
+
+## Input
+
+<ParamField body="action" type="string" required>One of `account.activated`, `account.restricted`, `account.rejected`, `payout.processing`, `payout.paid`, `payout.failed`, `payout.canceled`, `not_supported`.</ParamField>
+<ParamField body="data" type="object">Event target; nothing happens when omitted.
+  <Expandable title="properties">
+    <ParamField body="id" type="string" required>The ID of the payout account (for `account.*` actions) or the payout (for `payout.*` actions).</ParamField>
+  </Expandable>
+</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">No return value; the matching account or payout status is updated as a side effect.</ResponseField>

package/content/references/workflows/product/confirm-products.mdx

@@ -0,0 +1,46 @@
+---
+title: "confirmProductsWorkflow"
+description: "Approve proposed products and publish them to the catalog."
+---
+
+Approves products awaiting review: validates every product is in `proposed` status, sets them to `published`, and records a confirmed `STATUS_CHANGE` audit action per product. Triggered by `POST /admin/products/:id/confirm`. Emits `product.published` with one `{ id, internal_note }` entry per product.
+
+## Usage
+
+```ts
+import { confirmProductsWorkflow } from "@mercurjs/core/workflows"
+
+await confirmProductsWorkflow(container).run({
+  input: {
+    product_ids: ["prod_01H..."],
+    actor_id: "user_01H...",
+    internal_note: "Approved after review",
+  },
+})
+```
+
+## Input
+
+<ParamField body="product_ids" type="string[]" required>
+  Ids of the products to publish. Every product must currently be in `proposed` status.
+</ParamField>
+
+<ParamField body="actor_id" type="string">
+  Actor id recorded on the audit trail entry.
+</ParamField>
+
+<ParamField body="internal_note" type="string">
+  Operator-only note stored on the audit change and included in the emitted event.
+</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">
+  Returns nothing; the products are updated in place.
+</ResponseField>
+
+## Hooks
+
+<ResponseField name="productsConfirmed" type="hook">
+  Runs after publishing with `{ product_ids, internal_note }`.
+</ResponseField>

package/content/references/workflows/product/create-products.mdx

@@ -0,0 +1,63 @@
+---
+title: "createProductsWorkflow"
+description: "Create master catalog products with seller eligibility and creator attribution."
+---
+
+Creates master catalog products, resolving Mercur `attributes` inputs into native product options and value links, linking each product to its eligible sellers (`product_seller` links), and recording a confirmed `PRODUCT_ADD` audit action attributed to `created_by`. Triggered by `POST /admin/products` and `POST /vendor/products`. Variants default to `manage_inventory: false` unless set explicitly. Emits `product.created`.
+
+## Usage
+
+```ts
+import { createProductsWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createProductsWorkflow(container).run({
+  input: {
+    products: [{ title: "Linen Shirt", seller_ids: ["sel_01H..."] }],
+    created_by: "sel_01H...",
+  },
+})
+```
+
+## Input
+
+<ParamField body="products" type="object[]" required>
+  Products to create.
+  <Expandable title="properties">
+    <ParamField body="title" type="string" required>
+      The product title. All Medusa `CreateProductDTO` fields (handle, description, status, variants, categories, images, etc.) are accepted, except `options`.
+    </ParamField>
+    <ParamField body="attributes" type="ProductAttributeBatchAdd[]">
+      Attribute inputs resolved into native options and value links — `{ id, value_ids }` / `{ id, value }` for existing attributes, or `{ title, values, is_variant_axis }` / `{ title, type, value }` for inline ones. Do not pass native `options`.
+    </ParamField>
+    <ParamField body="seller_ids" type="string[]">
+      Seller ids to link to the product as eligible sellers.
+    </ParamField>
+    <ParamField body="variants" type="object[]">
+      Variants to create; `options` name-maps bind them to axis attributes. `manage_inventory` defaults to `false`.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="created_by" type="string" required>
+  Actor id recorded on the `PRODUCT_ADD` audit action.
+</ParamField>
+
+<ParamField body="additional_data" type="object">
+  Arbitrary data forwarded to the underlying Medusa create workflows and the `productsCreated` hook.
+</ParamField>
+
+## Result
+
+<ResponseField name="result" type="ProductDTO[]">
+  The created products, including their generated ids, options, and statuses.
+</ResponseField>
+
+## Hooks
+
+<ResponseField name="validate" type="hook">
+  Runs first with `{ input, products }` — use it to reject invalid payloads before anything is created.
+</ResponseField>
+
+<ResponseField name="productsCreated" type="hook">
+  Runs after creation with `{ products, additional_data }`.
+</ResponseField>

package/content/references/workflows/product/link-sellers-to-product-category.mdx

@@ -0,0 +1,40 @@
+---
+title: "linkSellersToProductCategoryWorkflow"
+description: "Add or remove seller eligibility links on a product category."
+---
+
+Updates which sellers are allowed to sell in a product category by creating and removing seller–category links in one call — the mechanism behind restricted categories. Triggered by `POST /admin/product-categories/:id/sellers`. No events are emitted.
+
+## Usage
+
+```ts
+import { linkSellersToProductCategoryWorkflow } from "@mercurjs/core/workflows"
+
+await linkSellersToProductCategoryWorkflow(container).run({
+  input: {
+    id: "pcat_01H...",
+    add: ["sel_01H..."],
+    remove: ["sel_01J..."],
+  },
+})
+```
+
+## Input
+
+<ParamField body="id" type="string" required>
+  Id of the product category whose seller links are being updated.
+</ParamField>
+
+<ParamField body="add" type="string[]">
+  Seller ids to link to the category.
+</ParamField>
+
+<ParamField body="remove" type="string[]">
+  Seller ids to unlink from the category.
+</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">
+  Returns nothing; the links are created and removed in place.
+</ResponseField>

package/content/references/workflows/product/link-sellers-to-product.mdx

@@ -0,0 +1,40 @@
+---
+title: "linkSellersToProductWorkflow"
+description: "Add or remove seller eligibility links on a master product."
+---
+
+Updates which sellers are eligible for a master product by creating and removing `product_seller` links in one call. Triggered by `POST /admin/products/:id/sellers`. No events are emitted and the product record itself is untouched.
+
+## Usage
+
+```ts
+import { linkSellersToProductWorkflow } from "@mercurjs/core/workflows"
+
+await linkSellersToProductWorkflow(container).run({
+  input: {
+    id: "prod_01H...",
+    add: ["sel_01H..."],
+    remove: ["sel_01J..."],
+  },
+})
+```
+
+## Input
+
+<ParamField body="id" type="string" required>
+  Id of the product whose seller links are being updated.
+</ParamField>
+
+<ParamField body="add" type="string[]">
+  Seller ids to link to the product.
+</ParamField>
+
+<ParamField body="remove" type="string[]">
+  Seller ids to unlink from the product.
+</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">
+  Returns nothing; the links are created and removed in place.
+</ResponseField>

package/content/references/workflows/product/reject-product.mdx

@@ -0,0 +1,46 @@
+---
+title: "rejectProductWorkflow"
+description: "Reject a proposed product submission with an optional message to the vendor."
+---
+
+Rejects a product awaiting review: validates the product is in `proposed` status, sets it to `rejected`, and records a confirmed `STATUS_CHANGE` audit action whose `external_note` carries the rejection message. Triggered by `POST /admin/products/:id/reject`. Emits `product.rejected` with `{ id, message }`.
+
+## Usage
+
+```ts
+import { rejectProductWorkflow } from "@mercurjs/core/workflows"
+
+await rejectProductWorkflow(container).run({
+  input: {
+    product_id: "prod_01H...",
+    message: "Images do not meet marketplace guidelines",
+    actor_id: "user_01H...",
+  },
+})
+```
+
+## Input
+
+<ParamField body="product_id" type="string" required>
+  Id of the product to reject. Must currently be in `proposed` status.
+</ParamField>
+
+<ParamField body="message" type="string">
+  Vendor-facing rejection reason, stored as the audit change's `external_note` and included in the emitted event.
+</ParamField>
+
+<ParamField body="actor_id" type="string">
+  Actor id recorded on the audit trail entry.
+</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">
+  Returns nothing; the product status is updated in place.
+</ResponseField>
+
+## Hooks
+
+<ResponseField name="productRejected" type="hook">
+  Runs after rejection with `{ product_id, message }`.
+</ResponseField>

package/content/references/workflows/product/request-product-change.mdx

@@ -0,0 +1,46 @@
+---
+title: "requestProductChangeWorkflow"
+description: "Ask a vendor to revise a proposed product submission without changing its status."
+---
+
+Records an operator's request for revisions on a product awaiting review. Validates the product is in `proposed` status and records a confirmed `CHANGE_REQUESTED` audit action — the product itself is not mutated; the audit entry and its `external_note` are the durable signal to the vendor. Triggered by `POST /admin/products/:id/request-changes`. Emits `product.change-requested` with `{ id, message, actor_id }`.
+
+## Usage
+
+```ts
+import { requestProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+await requestProductChangeWorkflow(container).run({
+  input: {
+    product_id: "prod_01H...",
+    message: "Please add care instructions to the description",
+    actor_id: "user_01H...",
+  },
+})
+```
+
+## Input
+
+<ParamField body="product_id" type="string" required>
+  Id of the product to request changes on. Must currently be in `proposed` status.
+</ParamField>
+
+<ParamField body="message" type="string">
+  Vendor-facing revision request, stored as the audit change's `external_note` and in the action's `details.message`.
+</ParamField>
+
+<ParamField body="actor_id" type="string">
+  Actor id recorded on the audit trail entry.
+</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">
+  Returns nothing; only an audit entry is created.
+</ResponseField>
+
+## Hooks
+
+<ResponseField name="productChangeRequested" type="hook">
+  Runs after the audit entry is recorded with `{ product_id, message }`.
+</ResponseField>

package/content/references/workflows/product-attribute/add-product-attributes-to-product.mdx

@@ -0,0 +1,49 @@
+---
+title: "addProductAttributesToProductWorkflow"
+description: "Attach existing or inline attributes (and their values) to a product."
+---
+
+Handles the `add` portion of the attribute batch engine (`createAndLinkProductAttributesToProductWorkflow`). Existing `text`/`unit` attributes get a new value created from `value`; `toggle` links the seeded `true`/`false` value; existing variant-axis `multi_select` attributes have their mirror `ProductOption` attached to the product with the selected value subset. Inline refs create a product-scoped attribute — axis refs also create an exclusive `ProductOption` — and link the values to the product.
+
+## Usage
+
+```ts
+import { addProductAttributesToProductWorkflow } from "@mercurjs/core/workflows"
+
+await addProductAttributesToProductWorkflow(container).run({
+  input: {
+    product_id: "prod_123",
+    add: [
+      { id: "pattr_material", value: "Cotton" },
+      { title: "Size", values: ["S", "M", "L"], is_variant_axis: true },
+    ],
+  },
+})
+```
+
+Also accepts an array of `{ product_id, add }` items to process several products in one run.
+
+## Input
+
+<ParamField body="product_id" type="string" required>The product to attach the attributes to.</ParamField>
+<ParamField body="add" type="ProductAttributeBatchAdd[]" required>
+  Attribute refs to attach.
+  <Expandable title="properties">
+    <ParamField body="id" type="string">Id of an existing attribute (existing form).</ParamField>
+    <ParamField body="value_ids" type="string[]">Attribute value ids to link (select types / axis subset).</ParamField>
+    <ParamField body="value" type="string | number | boolean">Scalar for `text` / `unit` / `toggle` attributes.</ParamField>
+    <ParamField body="title" type="string">Name of the inline attribute to create (inline form).</ParamField>
+    <ParamField body="type" type="AttributeType">One of `single_select`, `multi_select`, `unit`, `toggle`, `text`; inferred when omitted (`is_variant_axis` ⇒ `multi_select`, boolean `value` ⇒ `toggle`, else `text`).</ParamField>
+    <ParamField body="values" type="string[]">Value names to create for inline multi-value attributes.</ParamField>
+    <ParamField body="is_variant_axis" type="boolean">Create the inline attribute as a variant axis with an exclusive product option.</ParamField>
+    <ParamField body="is_filterable" type="boolean">Whether the inline attribute is filterable. Defaults to `false`.</ParamField>
+    <ParamField body="is_required" type="boolean">Whether the inline attribute is required. Defaults to `false`.</ParamField>
+    <ParamField body="description" type="string | null">Description of the inline attribute.</ParamField>
+    <ParamField body="metadata" type="object | null">Custom key-value data on the inline attribute.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">No return value.</ResponseField>