@mercurjs/docs 2.2.0-canary.40

package/content/references/workflows/product-attribute/create-and-link-product-attributes-to-product.mdx

@@ -0,0 +1,46 @@
+---
+title: "createAndLinkProductAttributesToProductWorkflow"
+description: "Batch attach, detach, and update attribute selections on a product."
+---
+
+The batch orchestrator behind `POST /admin/products/:id/attributes/batch` and `POST /vendor/products/:id/attributes/batch`. Delegates to `removeProductAttributesFromProductWorkflow`, `addProductAttributesToProductWorkflow`, and `updateProductAttributesOnProductWorkflow`, applied in the order **remove → add → update** so removing and re-adding the same attribute in one call resolves correctly.
+
+## Usage
+
+```ts
+import { createAndLinkProductAttributesToProductWorkflow } from "@mercurjs/core/workflows"
+
+await createAndLinkProductAttributesToProductWorkflow(container).run({
+  input: {
+    product_id: "prod_123",
+    add: [{ id: "pattr_color", value_ids: ["pattrval_red"] }],
+    remove: ["pattr_old"],
+    update: [{ id: "pattr_size", add: ["pattrval_xl"] }],
+  },
+})
+```
+
+## Input
+
+<ParamField body="product_id" type="string" required>The product whose attributes are being managed.</ParamField>
+<ParamField body="add" type="ProductAttributeBatchAdd[]">Attributes to attach — existing (`{ id, value_ids | value }`) or inline (`{ title, type?, value | values, is_variant_axis? }`).</ParamField>
+<ParamField body="remove" type="string[]">Ids of attributes to detach; product-scoped attributes are deleted, shared ones are unlinked.</ParamField>
+<ParamField body="update" type="ProductAttributeBatchUpdate[]">Per-attribute selection changes (`{ id, title?, add?, remove?, value? }`).</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">No return value.</ResponseField>
+
+## Hooks
+
+- `validate` — runs before any mutation with `{ input }`; throw to reject the batch.
+- `productAttributesLinked` — runs after all sub-workflows with `{ product_id }`.
+
+```ts
+createAndLinkProductAttributesToProductWorkflow.hooks.productAttributesLinked(
+  async ({ product_id }) => {
+    // re-index the product
+  },
+)
+```

package/content/references/workflows/product-attribute/create-product-attribute-values.mdx

@@ -0,0 +1,43 @@
+---
+title: "createProductAttributeValuesWorkflow"
+description: "Add values to an attribute, mirroring them onto its product option."
+---
+
+Creates values on an existing attribute. If the attribute is a variant-axis `multi_select` with a mirror `ProductOption`, the option's value list is extended first and each new attribute value is bound to its option value via `product_option_value_id`. Triggered by `POST /admin/product-attributes/:id/values`. Emits `product-attribute-value.created`.
+
+## Usage
+
+```ts
+import { createProductAttributeValuesWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createProductAttributeValuesWorkflow(container).run({
+  input: {
+    attribute_id: "pattr_color",
+    values: [{ name: "Green" }, { name: "Yellow", rank: 5 }],
+  },
+})
+```
+
+## Input
+
+<ParamField body="attribute_id" type="string" required>The attribute to add the values to.</ParamField>
+<ParamField body="values" type="CreateProductAttributeValueDTO[]" required>
+  Values to create.
+  <Expandable title="properties">
+    <ParamField body="name" type="string" required>Display name of the value.</ParamField>
+    <ParamField body="handle" type="string">URL-safe handle; auto-generated when omitted.</ParamField>
+    <ParamField body="rank" type="number">Sort rank.</ParamField>
+    <ParamField body="is_active" type="boolean">Whether the value is active.</ParamField>
+    <ParamField body="metadata" type="object | null">Custom key-value data.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="ProductAttributeValueDTO[]">The created values.</ResponseField>
+
+## Hooks
+
+- `validate` — runs before creation with `{ input }`.
+- `productAttributeValuesCreated` — runs after creation with `{ values, additional_data }`.

package/content/references/workflows/product-attribute/create-product-attributes.mdx

@@ -0,0 +1,56 @@
+---
+title: "createProductAttributesWorkflow"
+description: "Create catalog attributes with values, mirror options, and category links."
+---
+
+Creates product attributes and their values. Variant-axis `multi_select` attributes also get a shared mirror `ProductOption` created, with each value bound to its option value. Optional `category_ids` create category links per attribute. Triggered by `POST /admin/product-attributes`. Emits `product-attribute.created`.
+
+## Usage
+
+```ts
+import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createProductAttributesWorkflow(container).run({
+  input: {
+    attributes: [
+      {
+        name: "Color",
+        type: "multi_select",
+        is_variant_axis: true,
+        values: [{ name: "Red" }, { name: "Blue" }],
+        category_ids: ["pcat_apparel"],
+      },
+    ],
+  },
+})
+```
+
+## Input
+
+<ParamField body="attributes" type="(CreateProductAttributeDTO & { category_ids?: string[] })[]" required>
+  Attributes to create.
+  <Expandable title="properties">
+    <ParamField body="name" type="string" required>Display name of the attribute.</ParamField>
+    <ParamField body="type" type="AttributeType" required>One of `single_select`, `multi_select`, `unit`, `toggle`, `text`.</ParamField>
+    <ParamField body="handle" type="string">URL-safe handle; auto-generated when omitted.</ParamField>
+    <ParamField body="description" type="string | null">Description of the attribute.</ParamField>
+    <ParamField body="is_required" type="boolean">Whether products must carry this attribute.</ParamField>
+    <ParamField body="is_filterable" type="boolean">Whether the attribute is exposed as a storefront filter.</ParamField>
+    <ParamField body="is_variant_axis" type="boolean">Mirror the attribute as a shared `ProductOption` (with `type: multi_select`).</ParamField>
+    <ParamField body="rank" type="number">Sort rank.</ParamField>
+    <ParamField body="is_active" type="boolean">Whether the attribute is active.</ParamField>
+    <ParamField body="values" type="CreateProductAttributeValueDTO[]">Values to create (`{ name, handle?, rank?, is_active?, metadata? }`).</ParamField>
+    <ParamField body="category_ids" type="string[]">Category ids to link the attribute to.</ParamField>
+    <ParamField body="metadata" type="object | null">Custom key-value data.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="ProductAttributeDTO[]">The created attributes.</ResponseField>
+
+## Hooks
+
+- `validate` — runs before creation with `{ input }`.
+- `productAttributesCreated` — runs after creation with `{ attributes, additional_data }`.

package/content/references/workflows/product-attribute/delete-product-attribute-values.mdx

@@ -0,0 +1,30 @@
+---
+title: "deleteProductAttributeValuesWorkflow"
+description: "Delete attribute values and shrink the mirror option accordingly."
+---
+
+Deletes attribute values by id. When the deleted values belong to a single variant-axis `multi_select` attribute with a mirror `ProductOption`, the option's value list is rewritten to the attribute's remaining value names. Triggered by `DELETE /admin/product-attributes/:id/values/:value_id`; also run internally by the batch update engine. Emits `product-attribute-value.deleted`.
+
+## Usage
+
+```ts
+import { deleteProductAttributeValuesWorkflow } from "@mercurjs/core/workflows"
+
+await deleteProductAttributeValuesWorkflow(container).run({
+  input: { ids: ["pattrval_123", "pattrval_456"] },
+})
+```
+
+## Input
+
+<ParamField body="ids" type="string[]" required>Ids of the attribute values to delete.</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">No return value.</ResponseField>
+
+## Hooks
+
+- `validate` — runs before deletion with `{ input }`.
+- `productAttributeValuesDeleted` — runs after deletion with `{ ids, additional_data }`.

package/content/references/workflows/product-attribute/delete-product-attributes.mdx

@@ -0,0 +1,30 @@
+---
+title: "deleteProductAttributesWorkflow"
+description: "Delete attributes and their mirror product options."
+---
+
+Deletes product attributes after validating none of them is still linked to a product or category. Mirror `ProductOption`s of axis attributes are deleted alongside. Triggered by `DELETE /admin/product-attributes/:id`; also run internally when detaching product-scoped attributes. Emits `product-attribute.deleted`.
+
+## Usage
+
+```ts
+import { deleteProductAttributesWorkflow } from "@mercurjs/core/workflows"
+
+await deleteProductAttributesWorkflow(container).run({
+  input: { ids: ["pattr_123"] },
+})
+```
+
+## Input
+
+<ParamField body="ids" type="string[]" required>Ids of the attributes to delete; the workflow throws if an attribute is still linked.</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">No return value.</ResponseField>
+
+## Hooks
+
+- `validate` — runs before deletion with `{ input }`.
+- `productAttributesDeleted` — runs after deletion with `{ ids, additional_data }`.

package/content/references/workflows/product-attribute/remove-product-attributes-from-product.mdx

@@ -0,0 +1,29 @@
+---
+title: "removeProductAttributesFromProductWorkflow"
+description: "Detach attributes from a product, deleting product-scoped ones."
+---
+
+Handles the `remove` portion of the attribute batch engine (`createAndLinkProductAttributesToProductWorkflow`). Rejects required attributes, dismisses the product's value links for every listed attribute, detaches the mirror `ProductOption` for shared axis attributes, and runs `deleteProductAttributesWorkflow` for product-scoped (inline) attributes so their exclusive options are deleted too.
+
+## Usage
+
+```ts
+import { removeProductAttributesFromProductWorkflow } from "@mercurjs/core/workflows"
+
+await removeProductAttributesFromProductWorkflow(container).run({
+  input: {
+    product_id: "prod_123",
+    remove: ["pattr_color", "pattr_custom_size"],
+  },
+})
+```
+
+## Input
+
+<ParamField body="product_id" type="string" required>The product to detach the attributes from.</ParamField>
+<ParamField body="remove" type="string[]" required>Ids of the attributes to detach; attributes with `is_required: true` cause the workflow to throw.</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">No return value.</ResponseField>

package/content/references/workflows/product-attribute/update-product-attribute-values.mdx

@@ -0,0 +1,44 @@
+---
+title: "updateProductAttributeValuesWorkflow"
+description: "Update attribute values matching a selector and re-sync the mirror option."
+---
+
+Updates attribute values by selector. When the touched values belong to a single variant-axis `multi_select` attribute with a mirror `ProductOption`, the option's value list is rewritten from the attribute's current value names. Triggered by `POST /admin/product-attributes/:id/values/:value_id`. Emits `product-attribute-value.updated`.
+
+## Usage
+
+```ts
+import { updateProductAttributeValuesWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await updateProductAttributeValuesWorkflow(container).run({
+  input: {
+    selector: { id: "pattrval_123" },
+    update: { name: "Dark Green" },
+  },
+})
+```
+
+## Input
+
+<ParamField body="selector" type="object" required>Filter for the values to update, e.g. `{ id: "pattrval_123" }`.</ParamField>
+<ParamField body="update" type="UpdateProductAttributeValueDTO" required>
+  Fields to set on every matched value.
+  <Expandable title="properties">
+    <ParamField body="name" type="string">New display name.</ParamField>
+    <ParamField body="handle" type="string">New handle.</ParamField>
+    <ParamField body="rank" type="number">Sort rank.</ParamField>
+    <ParamField body="is_active" type="boolean">Whether the value is active.</ParamField>
+    <ParamField body="product_option_value_id" type="string | null">Bound mirror option value.</ParamField>
+    <ParamField body="metadata" type="object | null">Custom key-value data.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="ProductAttributeValueDTO[]">The updated values.</ResponseField>
+
+## Hooks
+
+- `validate` — runs before the update with `{ input }`.
+- `productAttributeValuesUpdated` — runs after the update with `{ values, additional_data }`.

package/content/references/workflows/product-attribute/update-product-attributes-on-product.mdx

@@ -0,0 +1,41 @@
+---
+title: "updateProductAttributesOnProductWorkflow"
+description: "Mutate a product's per-attribute value selections."
+---
+
+Handles the `update` portion of the attribute batch engine (`createAndLinkProductAttributesToProductWorkflow`). For shared axis attributes it adjusts the per-product value subset of the mirror option and keeps the value-link pivot in sync; for exclusive (product-scoped) axis attributes it creates or deletes values on the exclusive option; for `text`/`unit` it swaps the linked value's name (or creates one); for `toggle` it re-links the matching `true`/`false` value. A `title` on a product-scoped attribute renames it via `updateProductAttributesWorkflow`.
+
+## Usage
+
+```ts
+import { updateProductAttributesOnProductWorkflow } from "@mercurjs/core/workflows"
+
+await updateProductAttributesOnProductWorkflow(container).run({
+  input: {
+    product_id: "prod_123",
+    update: [
+      { id: "pattr_size", add: ["pattrval_xl"], remove: ["pattrval_s"] },
+      { id: "pattr_material", value: "Linen" },
+    ],
+  },
+})
+```
+
+## Input
+
+<ParamField body="product_id" type="string" required>The product whose attribute selections are updated.</ParamField>
+<ParamField body="update" type="ProductAttributeBatchUpdate[]" required>
+  Per-attribute updates.
+  <Expandable title="properties">
+    <ParamField body="id" type="string" required>Id of the existing attribute to update.</ParamField>
+    <ParamField body="title" type="string">New name; only honoured for product-scoped attributes and propagated to the mirror option title.</ParamField>
+    <ParamField body="add" type="(string | { value: string })[]">Value ids to add (shared axis subset) or new value objects to create (exclusive axis).</ParamField>
+    <ParamField body="remove" type="string[]">Value ids to remove from the selection (exclusive-axis values are deleted).</ParamField>
+    <ParamField body="value" type="string | number | boolean">New scalar for `text` / `unit` / `toggle` attributes.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">No return value.</ResponseField>

package/content/references/workflows/product-attribute/update-product-attributes.mdx

@@ -0,0 +1,48 @@
+---
+title: "updateProductAttributesWorkflow"
+description: "Update attributes matching a selector and sync mirror option titles."
+---
+
+Updates product attributes by selector. When `name` changes, the mirror `ProductOption` title of any affected axis attribute is updated to match. Triggered by `POST /admin/product-attributes/:id`. Emits `product-attribute.updated`.
+
+## Usage
+
+```ts
+import { updateProductAttributesWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await updateProductAttributesWorkflow(container).run({
+  input: {
+    selector: { id: "pattr_123" },
+    update: { name: "Colour", is_filterable: true },
+  },
+})
+```
+
+## Input
+
+<ParamField body="selector" type="object" required>Filter for the attributes to update, e.g. `{ id: "pattr_123" }`.</ParamField>
+<ParamField body="update" type="UpdateProductAttributeDTO" required>
+  Fields to set on every matched attribute.
+  <Expandable title="properties">
+    <ParamField body="name" type="string">New display name; propagated to mirror option titles.</ParamField>
+    <ParamField body="handle" type="string">New handle.</ParamField>
+    <ParamField body="description" type="string | null">New description.</ParamField>
+    <ParamField body="type" type="AttributeType">One of `single_select`, `multi_select`, `unit`, `toggle`, `text`.</ParamField>
+    <ParamField body="is_required" type="boolean">Whether products must carry this attribute.</ParamField>
+    <ParamField body="is_filterable" type="boolean">Whether the attribute is a storefront filter.</ParamField>
+    <ParamField body="is_variant_axis" type="boolean">Whether the attribute is a variant axis.</ParamField>
+    <ParamField body="rank" type="number">Sort rank.</ParamField>
+    <ParamField body="is_active" type="boolean">Whether the attribute is active.</ParamField>
+    <ParamField body="metadata" type="object | null">Custom key-value data.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="ProductAttributeDTO[]">The updated attributes.</ResponseField>
+
+## Hooks
+
+- `validate` — runs before the update with `{ input }`.
+- `productAttributesUpdated` — runs after the update with `{ attributes, additional_data }`.

package/content/references/workflows/product-attribute/upsert-product-attribute-values.mdx

@@ -0,0 +1,43 @@
+---
+title: "upsertProductAttributeValuesWorkflow"
+description: "Create or update attribute values in one call, keyed by id presence."
+---
+
+Splits the given values by `id`: entries without an id are created on the attribute, entries with an id are updated in place. Unlike the create/update value workflows it does not touch the mirror `ProductOption` (renaming a value in place does not re-sync the mirrored option) and it emits no events.
+
+## Usage
+
+```ts
+import { upsertProductAttributeValuesWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await upsertProductAttributeValuesWorkflow(container).run({
+  input: {
+    attribute_id: "pattr_color",
+    values: [
+      { name: "Teal" },
+      { id: "pattrval_123", name: "Navy Blue" },
+    ],
+  },
+})
+```
+
+## Input
+
+<ParamField body="attribute_id" type="string" required>The attribute the values belong to.</ParamField>
+<ParamField body="values" type="UpsertProductAttributeValueDTO[]" required>
+  Values to create (no `id`) or update (with `id`).
+  <Expandable title="properties">
+    <ParamField body="id" type="string">Existing value id; omit to create a new value.</ParamField>
+    <ParamField body="name" type="string">Display name of the value.</ParamField>
+    <ParamField body="handle" type="string">URL-safe handle.</ParamField>
+    <ParamField body="rank" type="number">Sort rank.</ParamField>
+    <ParamField body="is_active" type="boolean">Whether the value is active.</ParamField>
+    <ParamField body="product_option_value_id" type="string | null">Bound mirror option value.</ParamField>
+    <ParamField body="metadata" type="object | null">Custom key-value data.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="ProductAttributeValueDTO[]">The created values followed by the updated values.</ResponseField>

package/content/references/workflows/product-edit/auto-confirm-product-change.mdx

@@ -0,0 +1,39 @@
+---
+title: "autoConfirmProductChangeWorkflow"
+description: "Conditionally confirm a ProductChange based on the product_request feature flag."
+---
+
+Decides whether a freshly staged `ProductChange` should be confirmed immediately: it runs `confirmProductChangeWorkflow` for the change when `force` is `true` or the `product_request` feature flag is disabled, and does nothing otherwise (leaving the change `pending` for operator review). Run as a step by `stageProductChangeWorkflow`. Any events (`product-change.confirmed`) come from the nested confirm workflow.
+
+## Usage
+
+```ts
+import { autoConfirmProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+await autoConfirmProductChangeWorkflow(container).run({
+  input: {
+    change_id: "prch_01H...",
+    confirmed_by: "sel_01H...",
+  },
+})
+```
+
+## Input
+
+<ParamField body="change_id" type="string" required>
+  Id of the product change to (conditionally) confirm.
+</ParamField>
+
+<ParamField body="confirmed_by" type="string">
+  Actor id forwarded as `confirmed_by` to the confirm workflow.
+</ParamField>
+
+<ParamField body="force" type="boolean">
+  Confirm regardless of the `product_request` feature flag.
+</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">
+  Returns nothing; the change is either confirmed (and its actions applied) or left `pending`.
+</ResponseField>

package/content/references/workflows/product-edit/cancel-product-change.mdx

@@ -0,0 +1,49 @@
+---
+title: "cancelProductChangeWorkflow"
+description: "Cancel a pending ProductChange so its staged actions are never applied."
+---
+
+Cancels a pending `ProductChange`: validates the change exists and is still `pending`, then sets it to `canceled` with `canceled_by` and `canceled_at` — the staged actions are never applied to the master product. Triggered by `POST /admin/product-changes/:id/cancel` (operator) and `POST /vendor/products/:id/cancel` (vendor withdrawing their own edit). Emits `product-change.canceled` with `{ id }`.
+
+## Usage
+
+```ts
+import { cancelProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+await cancelProductChangeWorkflow(container).run({
+  input: {
+    id: "prch_01H...",
+    canceled_by: "sel_01H...",
+  },
+})
+```
+
+## Input
+
+<ParamField body="id" type="string" required>
+  Id of the product change to cancel. Must exist and be in `pending` status.
+</ParamField>
+
+<ParamField body="canceled_by" type="string">
+  Actor id recorded as the canceler on the change.
+</ParamField>
+
+<ParamField body="additional_data" type="object">
+  Arbitrary data forwarded to the `productChangeCanceled` hook.
+</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">
+  Returns nothing; the change status is updated in place.
+</ResponseField>
+
+## Hooks
+
+<ResponseField name="validate" type="hook">
+  Runs first with `{ input }` — use it to block cancellation.
+</ResponseField>
+
+<ResponseField name="productChangeCanceled" type="hook">
+  Runs after cancellation with `{ id, additional_data }`.
+</ResponseField>

package/content/references/workflows/product-edit/confirm-product-change.mdx

@@ -0,0 +1,57 @@
+---
+title: "confirmProductChangeWorkflow"
+description: "Confirm pending ProductChanges and apply their staged actions to the master product."
+---
+
+Confirms one or more pending `ProductChange` records: validates each change exists and is confirmable, marks them `confirmed` with `confirmed_by`, then runs the internal apply engine (`applyProductChangeActionsWorkflow`) to write the staged actions onto the master product. Triggered by `POST /admin/product-changes/:id/confirm`, and internally by `autoConfirmProductChangeWorkflow`. Emits `product-change.confirmed` with one `{ id }` per change.
+
+## Usage
+
+```ts
+import { confirmProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+await confirmProductChangeWorkflow(container).run({
+  input: {
+    ids: ["prch_01H..."],
+    confirmed_by: "user_01H...",
+  },
+})
+```
+
+## Input
+
+<ParamField body="ids" type="string[]" required>
+  Ids of the product changes to confirm. Each must exist and be in a confirmable (`pending`) state.
+</ParamField>
+
+<ParamField body="confirmed_by" type="string">
+  Actor id recorded as the confirmer on each change.
+</ParamField>
+
+<ParamField body="internal_note" type="string">
+  Operator-only note stored on each confirmed change.
+</ParamField>
+
+<ParamField body="external_note" type="string">
+  Vendor-facing note stored on each confirmed change.
+</ParamField>
+
+<ParamField body="additional_data" type="object">
+  Arbitrary data forwarded to the `productChangeConfirmed` hook.
+</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">
+  Returns nothing; the changes are confirmed and their actions applied in place.
+</ResponseField>
+
+## Hooks
+
+<ResponseField name="validate" type="hook">
+  Runs first with `{ input }` — use it to block confirmation of specific changes.
+</ResponseField>
+
+<ResponseField name="productChangeConfirmed" type="hook">
+  Runs after actions are applied with `{ ids, additional_data }`.
+</ResponseField>

package/content/references/workflows/product-edit/create-product-change.mdx

@@ -0,0 +1,72 @@
+---
+title: "createProductChangeWorkflow"
+description: "Create ProductChange records after validating no pending change exists per product."
+---
+
+Creates one or more `ProductChange` records — the staging entity for vendor edits on shared master products. Validates that none of the referenced products already has a `pending` change before inserting. Emits `product-change.created` with one `{ id }` entry per change. Actions are attached separately (see `stageProductChangeWorkflow` for the combined flow).
+
+## Usage
+
+```ts
+import { createProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createProductChangeWorkflow(container).run({
+  input: {
+    changes: [
+      { product_id: "prod_01H...", created_by: "sel_01H..." },
+    ],
+  },
+})
+```
+
+## Input
+
+<ParamField body="changes" type="CreateProductChangeDTO[]" required>
+  Changes to create.
+  <Expandable title="properties">
+    <ParamField body="product_id" type="string" required>
+      Id of the product the change targets. Must not already have a pending change.
+    </ParamField>
+    <ParamField body="status" type="ProductChangeStatus">
+      One of `pending`, `confirmed`, `declined`, `canceled`; audit-trail rows are created already `confirmed`.
+    </ParamField>
+    <ParamField body="created_by" type="string">
+      Actor id who authored the change.
+    </ParamField>
+    <ParamField body="internal_note" type="string">
+      Operator-only note.
+    </ParamField>
+    <ParamField body="external_note" type="string">
+      Vendor-facing note.
+    </ParamField>
+    <ParamField body="confirmed_by" type="string">
+      Confirming actor id, for pre-confirmed rows.
+    </ParamField>
+    <ParamField body="confirmed_at" type="Date">
+      Confirmation timestamp, for pre-confirmed rows.
+    </ParamField>
+    <ParamField body="metadata" type="object">
+      Arbitrary key-value data stored on the change.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="additional_data" type="object">
+  Arbitrary data forwarded to the `productChangeCreated` hook.
+</ParamField>
+
+## Result
+
+<ResponseField name="result" type="ProductChangeDTO[]">
+  The created change records with ids, statuses, and timestamps.
+</ResponseField>
+
+## Hooks
+
+<ResponseField name="validate" type="hook">
+  Runs first with `{ input }` — use it to reject invalid payloads before creation.
+</ResponseField>
+
+<ResponseField name="productChangeCreated" type="hook">
+  Runs after creation with `{ changes, additional_data }`.
+</ResponseField>