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

package/content/platform/product-edit/overview.mdx

@@ -1,85 +1,92 @@
 ---
-title: "Product Edit"
+title: "Product edits"
 sidebarTitle: "Overview"
-description: "Route every product edit through a reviewable, immutable change pipeline."
+description: "Review every seller edit to a shared product before it lands, and keep a record of who changed what."
 ---
 
-Use Mercur to keep a full audit trail of every product change and govern your
-master data before it changes.
+Use Mercur to put seller edits to the shared catalog through review, and to keep a durable history of every change to a product.
 
-Master-data governance depends on knowing who changed what, and reviewing it
-before it takes effect. The Product Edit domain is that auditable change
-pipeline. Every edit becomes an immutable, attributed `ProductChange` record that
-enters an approval queue, so no change to a shared product is silently written.
-Each record carries typed actions and a status lifecycle, and the trail records
-who changed what and who approved it.
+Products in Mercur form one shared catalog that every seller sells against, so a seller can’t write to a product directly. Each edit becomes a `ProductChange` record that holds typed actions, one per changed field, variant, or attribute. The change waits as `pending` until an operator confirms or declines it, or its author cancels it. Confirmed changes, together with publish approvals, rejections, and revision requests, form the product’s audit trail.
+
+<img className="block dark:hidden" src="/images/figures/product-edit-overview-light.svg" alt="A product's Changes list read through product.changes: a pending UPDATE from the seller sits on top of confirmed PRODUCT_ADD, CHANGE_REQUESTED, UPDATE, and STATUS_CHANGE records that form the audit trail." />
+<img className="hidden dark:block" src="/images/figures/product-edit-overview-dark.svg" alt="A product's Changes list read through product.changes: a pending UPDATE from the seller sits on top of confirmed PRODUCT_ADD, CHANGE_REQUESTED, UPDATE, and STATUS_CHANGE records that form the audit trail." />
 
 <Note>
-  **Product Edit ≠ product ownership.** Products are the shared master catalog,
-  and sellers sell against them through offers. Product Edit governs *changes* to
-  a product. It never makes a store the owner of one.
+  The Product Edit module (`MercurModules.PRODUCT_EDIT`) governs changes to a product. It never makes a store the owner of one. Products live in Medusa’s Product module, and sellers sell them through [offers](/platform/offer/overview).
 </Note>
 
+## How it works
+
+A seller edit moves through the pipeline in five steps:
+
+1. A vendor route runs an edit workflow such as `productEditUpdateProductWorkflow`, which diffs the input against the product and stages a `pending` change with one action per difference.
+2. `autoConfirmProductChangeWorkflow` runs right after staging. With the `product_request` feature flag on, the default, the change stays `pending`.
+3. An operator confirms or declines the change, or the seller cancels it.
+4. On confirm, `applyProductChangeActionsWorkflow` writes the actions to the product through Medusa’s product workflows and marks each action `applied`.
+5. Product creation, publish approvals, rejections, and revision requests are recorded as changes that start out `confirmed`, so the trail is complete without a review.
+
 ## Key features
 
-- **Immutable audit trail:** every edit is an attributed `ProductChange` that is never rewritten, only appended to and resolved.
-- **Typed change actions:** each edit is expressed as `ProductChangeAction` rows such as `UPDATE`, `VARIANT_*`, `ATTRIBUTE_*`, `STATUS_CHANGE`, or `PRODUCT_ADD/DELETE`.
-- **Approval queue:** a change moves `pending` → `confirmed` / `declined` / `canceled`, each through a dedicated workflow.
-- **Deferred application:** actions are applied to the product only on confirmation, then marked `applied`.
-- **Auto-confirm:** when review is off, staged changes confirm and apply immediately.
-- **Revision requests:** operators send a submission back to the vendor as a recorded `CHANGE_REQUESTED` audit action.
-- **One active change per product:** a product can't have two pending changes at once.
+The module covers the full path of an edit, from diff to audit record:
+
+- **Field-level diffs**: the edit workflows stage only the fields, variants, and attributes that differ from the current product
+- **Typed actions**: each change holds `ProductChangeAction` rows such as `UPDATE`, `VARIANT_ADD`, `ATTRIBUTE_UPDATE`, or `PRODUCT_DELETE`
+- **Review queue**: a change moves from `pending` to `confirmed`, `declined`, or `canceled`, each through its own workflow and event
+- **Deferred writes**: actions touch the product only when the change is confirmed
+- **Auto-confirm**: turn off the `product_request` flag, or pass `auto_confirm`, to apply a change in the same run
+- **Revision requests**: an operator sends a proposed product back to its seller with a recorded `CHANGE_REQUESTED` action
+- **One open change per author**: the edit workflows reject a new change while the same author has one pending on the product
 
 ## Get started
 
-Learn how the domain fits together:
+Learn how changes, actions, and statuses fit together.
 
 <CardGroup cols={2}>
   <Card title="The change pipeline" icon="clock-rotate-left" href="/platform/product-edit/concepts/change-pipeline">
-    The `ProductChange` record, immutability, and the audit trail.
+    How an edit becomes a `ProductChange` and how the audit trail builds up.
   </Card>
   <Card title="Change actions" icon="list-check" href="/platform/product-edit/concepts/change-actions">
-    The typed actions that make up a change and their `details`.
+    The action types, the `details` each one carries, and how they apply.
   </Card>
   <Card title="Status & auto-confirm" icon="arrows-rotate" href="/platform/product-edit/concepts/status-and-auto-confirm">
-    The status lifecycle, revision requests, and auto-confirm.
+    The status lifecycle, revision requests, and when a change skips review.
   </Card>
 </CardGroup>
 
 ## Examples
 
-Build against the Product Edit domain in your own code:
+Build against the change pipeline in your own server code.
 
 <CardGroup cols={2}>
   <Card title="Edit a product" icon="pen" href="/platform/product-edit/guides/edit-a-product">
-    Stage a product change from server code.
+    Stage field, variant, and attribute changes from a custom route.
   </Card>
   <Card title="Confirm or decline" icon="gavel" href="/platform/product-edit/guides/confirm-or-decline-a-change">
-    Resolve a pending change in code.
+    Resolve a pending change and react to the result.
   </Card>
   <Card title="Request a revision" icon="rotate-left" href="/platform/product-edit/guides/request-a-revision">
-    Send a submission back to the vendor.
+    Send a proposed product back to its seller with a message.
   </Card>
 </CardGroup>
 
 ## Resources
 
-Data models, workflows, service methods, and events for the Product Edit domain:
+The data models, links, workflows, service methods, and events behind product edits.
 
 <CardGroup cols={2}>
   <Card title="Data models" icon="table" href="/platform/product-edit/reference/data-models">
-    The `ProductChange` and `ProductChangeAction` entities.
+    The `ProductChange` and `ProductChangeAction` models and their enums.
   </Card>
   <Card title="Links" icon="link" href="/platform/product-edit/reference/links">
-    How the Product Edit domain links to other modules.
+    The read-only `product.changes` link to Medusa’s Product module.
   </Card>
   <Card title="Workflows" icon="diagram-project" href="/platform/product-edit/reference/workflows">
-    Create, confirm, decline, cancel, and stage workflows.
+    Staging, resolution, apply, edit, and audit workflows with their hooks.
   </Card>
   <Card title="Service" icon="gear" href="/platform/product-edit/reference/service">
-    Module service methods for working with records directly.
+    Generated methods on the Product Edit module service.
   </Card>
   <Card title="Events" icon="bell" href="/platform/product-edit/reference/events">
-    Events emitted as changes move through the pipeline.
+    The `product-change.*` events and the revision request event.
   </Card>
 </CardGroup>

package/content/platform/product-edit/reference/data-models.mdx

@@ -1,65 +1,91 @@
 ---
-title: "Data models"
+title: "Product Edit data models"
 sidebarTitle: "Data models"
-description: "The data models owned by the Product Edit domain."
+description: "Fields, enums, indexes, and relations of the ProductChange and ProductChangeAction models."
 ---
 
-The Product Edit domain is owned by the **Product Edit module**
-(`MercurModules.PRODUCT_EDIT`). This reference lists its data models and their
-fields.
+The Product Edit module, resolved with `MercurModules.PRODUCT_EDIT` (`"product_edit"`), owns two data models: `ProductChange` and `ProductChangeAction`. Both are defined in `packages/core/src/modules/product-edit/models`. Every model also gets `created_at`, `updated_at`, and `deleted_at` from Medusa.
 
 ## ProductChange
 
-Table `product_change`, id prefix `prodch`. A single reviewable edit to one
-product.
+A single reviewable edit to one product. Table `product_change`, id prefix `prodch`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
-| `id` | text | Primary key |
-| `product_id` | text | The product this change targets (indexed) |
-| `status` | enum | `ProductChangeStatus`, default `pending` (indexed) |
-| `internal_note` | text | Nullable; operator-only note |
-| `external_note` | text | Nullable; vendor-facing note |
-| `created_by` | text | Nullable; actor who staged the change |
-| `confirmed_by` / `confirmed_at` | text / dateTime | Nullable; set on confirm |
-| `declined_by` / `declined_at` | text / dateTime | Nullable; set on decline |
-| `declined_reason` | text | Nullable |
-| `canceled_by` / `canceled_at` | text / dateTime | Nullable; set on cancel |
-| `requires_action_by` / `requires_action_at` | text / dateTime | Nullable |
-| `requires_action_reason` | text | Nullable |
-| `metadata` | json | Nullable |
-
-Relations: `actions` (one-to-many `ProductChangeAction`, cascade-deleted with the
-change).
-
-<Note>
-  The `status` enum has four values: `pending`, `confirmed`, `declined`, and
-  `canceled`. A revision request is recorded as a `CHANGE_REQUESTED` audit action
-  rather than a distinct status.
-</Note>
+| `id` | `text` | Primary key, prefixed `prodch` |
+| `product_id` | `text` | The product the change targets |
+| `status` | `enum` | A `ProductChangeStatus` value. Default `pending` |
+| `internal_note` | `text`, nullable | Note for operators |
+| `external_note` | `text`, nullable | Note shown to the seller. Holds the message of a revision request |
+| `created_by` | `text`, nullable | Actor who staged the change: a seller id from vendor routes, a user id from admin routes |
+| `confirmed_by` | `text`, nullable | Actor who confirmed the change |
+| `confirmed_at` | `dateTime`, nullable | When the change was confirmed |
+| `declined_by` | `text`, nullable | Actor who declined the change |
+| `declined_at` | `dateTime`, nullable | When the change was declined |
+| `declined_reason` | `text`, nullable | Reason given on decline |
+| `canceled_by` | `text`, nullable | Actor who canceled the change |
+| `canceled_at` | `dateTime`, nullable | When the change was canceled |
+| `requires_action_by` | `text`, nullable | Reserved. No workflow writes it |
+| `requires_action_at` | `dateTime`, nullable | Reserved. No workflow writes it |
+| `requires_action_reason` | `text`, nullable | Reserved. No workflow writes it |
+| `metadata` | `json`, nullable | Custom key-value data |
+
+Relations:
+
+- **`actions`**: has many `ProductChangeAction`. The model cascades deletes to its actions
+
+Indexes on `status`, on `product_id`, and on `(product_id, status)`, all excluding soft-deleted rows.
 
 ## ProductChangeAction
 
-Table `product_change_action`, id prefix `prodchact`. A single typed operation
-inside a change.
+A single typed operation inside a change. Table `product_change_action`, id prefix `prodchact`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
-| `id` | text | Primary key |
-| `product_id` | text | The product the action targets (indexed) |
-| `product_change_id` | text | Nullable FK to the parent change (`ON DELETE SET NULL`, indexed) |
-| `ordering` | autoincrement | Deterministic apply order (indexed) |
-| `action` | text | A `ProductChangeActionType` value |
-| `details` | json | Default `{}`; the operation payload |
-| `internal_note` | text | Nullable |
-| `applied` | boolean | Default `false`; set `true` once written to the product |
+| `id` | `text` | Primary key, prefixed `prodchact` |
+| `product_id` | `text` | The product the action targets |
+| `product_change_id` | `text`, nullable | The parent change. The foreign key is `ON DELETE SET NULL` |
+| `ordering` | `autoincrement` | Insertion order across all actions |
+| `action` | `text` | A `ProductChangeActionType` value |
+| `details` | `json` | The operation payload. Default `{}` |
+| `reference` | `text`, nullable | Free-form type of a related record. Not set by Mercur |
+| `reference_id` | `text`, nullable | Free-form id of a related record. Not set by Mercur |
+| `internal_note` | `text`, nullable | Note for operators |
+| `applied` | `boolean` | `true` once the action is written to the product. Default `false` |
+
+Relations:
+
+- **`product_change`**: belongs to `ProductChange`, nullable
+
+Indexes on `product_change_id`, `product_id`, `(reference, reference_id)`, and `ordering`, all excluding soft-deleted rows.
+
+## ProductChangeStatus
+
+The values of `ProductChange.status`, exported from `@mercurjs/types`:
+
+| Value | Meaning |
+| --- | --- |
+| `pending` | Waiting for review |
+| `confirmed` | Approved and applied, or recorded as an audit change |
+| `declined` | Rejected by an operator |
+| `canceled` | Withdrawn before review |
 
-## Enums
+## ProductChangeActionType
 
-`ProductChangeStatus`: `pending`, `confirmed`, `declined`, `canceled`.
+The values of `ProductChangeAction.action`, exported from `@mercurjs/types`:
 
-`ProductChangeActionType`: `UPDATE`, `STATUS_CHANGE`, `VARIANT_ADD`,
-`VARIANT_UPDATE`, `VARIANT_REMOVE`, `ATTRIBUTE_ADD`, `ATTRIBUTE_UPDATE`,
-`ATTRIBUTE_REMOVE`, `PRODUCT_ADD`, `PRODUCT_DELETE`, `CHANGE_REQUESTED`.
+| Value | Applied on confirm |
+| --- | --- |
+| `UPDATE` | Yes |
+| `STATUS_CHANGE` | Yes |
+| `VARIANT_ADD` | Yes |
+| `VARIANT_UPDATE` | Yes |
+| `VARIANT_REMOVE` | Yes |
+| `ATTRIBUTE_ADD` | Yes |
+| `ATTRIBUTE_UPDATE` | Yes |
+| `ATTRIBUTE_REMOVE` | Yes |
+| `PRODUCT_DELETE` | Yes |
+| `PRODUCT_ADD` | No, audit only |
+| `CHANGE_REQUESTED` | No, audit only |
 
-Both enums are exported from `@mercurjs/types`.
+The `details` shape for each type is listed in [Change actions](/platform/product-edit/concepts/change-actions#action-types). The matching DTOs are `ProductChangeDTO` and `ProductChangeActionDTO`, and the create inputs are `CreateProductChangeDTO` and `CreateProductChangeActionDTO`, all from `@mercurjs/types`.

package/content/platform/product-edit/reference/events.mdx

@@ -1,22 +1,52 @@
 ---
-title: "Event reference"
+title: "Product Edit events"
 sidebarTitle: "Events"
-description: "Events emitted by the Product Edit domain, for subscribers and side effects."
+description: "Events emitted as product changes are staged and resolved, and when an operator requests a revision."
 ---
 
-The Product Edit domain emits events as changes move through the pipeline.
-Subscribe to them to run side effects instead of polling. Use them to notify a
-vendor, sync external systems, or kick off follow-up workflows.
+Product change workflows emit events after they commit, so you can run side effects, such as notifying a seller or reindexing search, without polling. The change events are in `ProductChangeWorkflowEvents`, and the revision request event is in `ProductWorkflowEvents`, both exported from `@mercurjs/core/workflows`.
+
+## Change events
+
+Each change event carries the id of one change. A workflow that handles several changes emits one event per change.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `product-change.created` | `stageProductChangeWorkflow` or `createProductChangeWorkflow` creates a change | `{ id }` |
+| `product-change.confirmed` | `confirmProductChangeWorkflow` confirms a change, including auto-confirm | `{ id }` |
+| `product-change.declined` | `rejectProductChangeWorkflow` declines a change | `{ id }` |
+| `product-change.canceled` | `cancelProductChangeWorkflow` cancels a change | `{ id }` |
+
+Audit changes from `recordProductAuditChangeWorkflow` emit no change event. An auto-confirmed change emits `product-change.created` and then `product-change.confirmed`.
+
+## Revision request event
+
+The revision request event comes from `requestProductChangeWorkflow`. Its `id` is the product id, because the request is recorded on the product rather than resolving a change.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `product.change-requested` | An operator requests a revision on a `proposed` product | `{ id, message, actor_id }` |
+
+## Subscribe to an event
+
+This subscriber loads a confirmed change with its actions:
 
 ```ts title="src/subscribers/product-change-confirmed.ts"
 import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
 
-export default async function productChangeConfirmedHandler({
+export default async function handler({
   event,
   container,
 }: SubscriberArgs<{ id: string }>) {
-  const changeId = event.data.id
-  // ...notify the vendor, sync search, etc.
+  const query = container.resolve("query")
+
+  const { data: [change] } = await query.graph({
+    entity: "product_change",
+    fields: ["product_id", "created_by", "actions.action"],
+    filters: { id: event.data.id },
+  })
+
+  // notify change.created_by that change.product_id was updated
 }
 
 export const config: SubscriberConfig = {
@@ -24,24 +54,4 @@ export const config: SubscriberConfig = {
 }
 ```
 
-## Change events
-
-| Event | Emitted when | Payload |
-| --- | --- | --- |
-| `product-change.created` | A change is staged | `{ id }` |
-| `product-change.confirmed` | A change is confirmed | `{ id }` |
-| `product-change.declined` | A change is declined | `{ id }` |
-| `product-change.canceled` | A change is canceled | `{ id }` |
-
-## Revision events
-
-| Event | Emitted when | Payload |
-| --- | --- | --- |
-| `product.change-requested` | An operator requests a revision | `{ id, message, actor_id }` |
-
-<Note>
-  `product.change-requested` carries the **product** id (not a change id) along
-  with the operator's `message` and `actor_id`, because a revision request is
-  recorded against the product's audit trail rather than resolving a pending
-  change.
-</Note>
+`created_by` tells you who to notify: a seller id for edits from the Vendor panel. To react to declines with the reason, read `declined_reason` the same way from a `product-change.declined` subscriber.

package/content/platform/product-edit/reference/links.mdx

@@ -1,39 +1,47 @@
 ---
-title: "Links to other modules"
+title: "Product Edit links"
 sidebarTitle: "Links"
-description: "How the Product Edit domain links to other modules across the marketplace."
+description: "The read-only link that exposes a product's change history as product.changes."
 ---
 
-Modules in Mercur never reference each other directly. They connect through
-**module links**. Once a link is defined, you retrieve related records with
-`query.graph` using the link alias.
+Mercur modules never import each other. They connect through module links, which you read with `query.graph`. The Product Edit module has one link, to Medusa’s Product module.
 
-## Product
+## Product to product changes
 
-The Product Edit domain links to the Product module so a product's change
-history hangs off the product itself.
+A read-only link that lists a product’s changes under the `changes` alias. It’s defined in `packages/core/src/links/product-change-link.ts`.
 
-| Linked module | Relationship |
-| --- | --- |
-| **Product** | A product has many changes (`product_change.product_id`, read-only). Exposed as `product.changes`. |
+| Side | Module | Linkable | Key |
+| --- | --- | --- | --- |
+| Source | Product (`Modules.PRODUCT`) | `product` | `id` |
+| Target | Product Edit (`MercurModules.PRODUCT_EDIT`) | `product_change` | `product_id` |
+
+- **Cardinality**: one product to many changes
+- **Alias**: `changes`, read as `product.changes`
+- **Storage**: no pivot table. The link reads the `product_id` column on `product_change`
+- **Writes**: none. The link is `readOnly`, so you create changes with the [workflows](/platform/product-edit/reference/workflows), never through the link
+
+Read a product’s history with its actions:
 
 ```ts
-const { data: products } = await query.graph({
+const query = container.resolve("query")
+
+const { data: [product] } = await query.graph({
   entity: "product",
-  fields: ["id", "title", "changes.status", "changes.actions.action"],
+  fields: [
+    "id",
+    "title",
+    "changes.id",
+    "changes.status",
+    "changes.created_by",
+    "changes.actions.action",
+    "changes.actions.details",
+  ],
+  filters: { id: "prod_01JD8Q1234567" },
 })
 ```
 
-<Note>
-  The link is **read-only** and has no pivot table. The FK lives directly on the
-  `product_change` row. It exists so you read the audit trail through
-  `product.changes`. You can't write a change through the link itself. Stage
-  changes with the [workflows](/platform/product-edit/reference/workflows).
-</Note>
+`product.changes` returns every change on the product, including audit changes and resolved ones. To filter by status, query the `product_change` entity with a `product_id` filter instead, because `query.graph` can’t filter on linked records.
 
-## Actor references
+## Actor fields
 
-The `created_by`, `confirmed_by`, `declined_by`, and `canceled_by` fields hold
-actor ids (the dashboard user who staged or resolved the change). They are plain
-text references for the audit trail, not module links, so they aren't resolved
-through `query.graph`.
+`created_by`, `confirmed_by`, `declined_by`, and `canceled_by` hold actor ids as plain text: a seller id when the change came from a vendor route, a user id when it came from an admin route. They aren’t module links, so `query.graph` can’t expand them. Resolve the seller or user yourself when you need their details.

package/content/platform/product-edit/reference/service.mdx

@@ -1,43 +1,62 @@
 ---
-title: "Service reference"
+title: "Product Edit module service"
 sidebarTitle: "Service"
-description: "The Product Edit module service methods for working with records directly."
+description: "Resolve the Product Edit module service and call its generated methods for changes and actions."
 ---
 
-The Product Edit 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 Edit module service, `ProductChangeModuleService`, reads and writes `ProductChange` and `ProductChangeAction` records directly. It’s a plain `MedusaService` with generated methods only, and no custom methods. Use it in subscribers, scheduled jobs, and workflow steps.
+
+## Resolve the service
+
+Resolve the service from the Medusa container with `MercurModules.PRODUCT_EDIT`:
 
 ```ts
 import { MercurModules } from "@mercurjs/types"
 
-const productChangeModuleService = container.resolve(MercurModules.PRODUCT_EDIT)
+const productEdit = container.resolve(MercurModules.PRODUCT_EDIT)
 
-const [changes, count] = await productChangeModuleService.listAndCountProductChanges({
-  status: "pending",
-})
+const [changes, count] = await productEdit.listAndCountProductChanges(
+  { product_id: "prod_01JD8Q1234567", status: "pending" },
+  { relations: ["actions"], take: 20 }
+)
 ```
 
-## Generated methods
+This returns the first 20 pending changes on a product, with their actions, and the total count. For a typed handle, import the class with `import type { ProductChangeModuleService } from "@mercurjs/core/modules/product-edit"` and pass it as the `resolve` generic.
+
+## ProductChange methods
+
+Medusa generates these methods for the `ProductChange` model:
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `retrieveProductChange` | `(id, config?)` | Retrieve one change. Throws if it doesn’t exist |
+| `listProductChanges` | `(filters?, config?)` | List changes matching the filters |
+| `listAndCountProductChanges` | `(filters?, config?)` | List changes and return `[changes, count]` |
+| `createProductChanges` | `(data)` | Create one change or an array of them |
+| `updateProductChanges` | `(data)` | Update by `id`, or pass `{ selector, data }` |
+| `deleteProductChanges` | `(ids)` | Delete changes. The model cascades deletes to their actions |
+| `softDeleteProductChanges` | `(ids, config?)` | Soft-delete changes |
+| `restoreProductChanges` | `(ids, config?)` | Restore soft-deleted changes |
+
+## ProductChangeAction methods
+
+The same set exists for `ProductChangeAction`:
 
-Each data model gets a standard set of auto-generated methods. For
-`ProductChange`:
+| Method | Signature | Description |
+| --- | --- | --- |
+| `retrieveProductChangeAction` | `(id, config?)` | Retrieve one action |
+| `listProductChangeActions` | `(filters?, config?)` | List actions matching the filters |
+| `listAndCountProductChangeActions` | `(filters?, config?)` | List actions and return `[actions, count]` |
+| `createProductChangeActions` | `(data)` | Create one action or an array of them |
+| `updateProductChangeActions` | `(data)` | Update by `id`, or pass `{ selector, data }` |
+| `deleteProductChangeActions` | `(ids)` | Delete actions |
+| `softDeleteProductChangeActions` | `(ids, config?)` | Soft-delete actions |
+| `restoreProductChangeActions` | `(ids, config?)` | Restore soft-deleted actions |
 
-| Method | Description |
-| --- | --- |
-| `createProductChanges(data)` | Create one or more changes |
-| `retrieveProductChange(id, config?)` | Retrieve a change by id |
-| `listProductChanges(filters?, config?)` | List changes matching filters |
-| `listAndCountProductChanges(filters?, config?)` | List changes with a total count |
-| `updateProductChanges(data)` | Update one or more changes |
-| `deleteProductChanges(ids)` | Delete one or more changes |
+## When to use a workflow instead
 
-The same set exists for `ProductChangeAction`: `createProductChangeActions`,
-`listProductChangeActions`, `updateProductChangeActions`, and so on.
+The service writes rows and nothing else. Setting `status` to `confirmed` through `updateProductChanges` doesn’t apply the actions, stamp `confirmed_at`, emit `product-change.confirmed`, or run the hooks.
 
 <Warning>
-  Prefer [workflows](/platform/product-edit/reference/workflows) for anything with
-  side effects (confirming, declining, applying actions). The service writes
-  records directly and does **not** apply actions to the product, emit events, or
-  run compensation.
+  Use the [workflows](/platform/product-edit/reference/workflows) for any status change. Keep the service for reads and for fields with no side effects, such as `metadata`.
 </Warning>