@mercurjs/docs 2.3.8-canary.3 → 2.3.8-canary.4

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

@@ -1,32 +1,93 @@
 ---
-title: "Workflows"
+title: "Payout workflows"
 sidebarTitle: "Workflows"
-description: "Payout account, onboarding, payout, and webhook workflows."
+description: "The 4 payout workflows and 6 payout steps exported from @mercurjs/core/workflows, with their inputs, steps, and hooks."
 ---
 
-This reference lists the workflows for the Payout domain. Import them from
-`@mercurjs/core/workflows` and run them against the Medusa container.
+The Payout module ships 4 workflows in `packages/core/src/workflows/payout`. Import them, and their steps, from `@mercurjs/core/workflows`. None of them emits a custom event. Medusa’s data-model events still fire for the records they write, as listed in [Events](/platform/payout/reference/events).
 
-## Account & onboarding workflows
+## createPayoutAccountWorkflow
 
-| Workflow | Input | Purpose |
+Creates a payout account for a seller through the provider and links it to the seller. Workflow id `create-payout-account-for-seller`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `seller_id` | `string` | Seller to create the account for |
+| `data` | `Record<string, unknown>`, optional | Passed to the provider; Stripe Connect needs `country` |
+| `context` | `PayoutProviderContext`, optional | Provider context, such as `idempotency_key` |
+
+Steps, in order:
+
+1. `validate-seller-payout-account`: fails with `Seller already has a payout account` when a `seller_payout_account` row exists
+2. `create-payout-account`: calls the service’s `createPayoutAccount`
+3. `create-remote-links`: links the seller and the account
+
+Returns the `PayoutAccountDTO`. Exposes no hooks.
+
+## createOnboardingWorkflow
+
+Creates or updates the onboarding record for a payout account through the provider. Workflow id `create-onboarding`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `account_id` | `string` | The `pacc` id |
+| `data` | `Record<string, unknown>`, optional | Merged over the account’s `data`; Stripe Connect needs `refresh_url` and `return_url` |
+| `context` | `PayoutProviderContext`, optional | Provider context, stored on the record |
+
+It runs one step, `create-onboarding`, and returns the `OnboardingDTO`. Exposes no hooks.
+
+## createPayoutWorkflow
+
+Pays the seller’s share of one order through the provider. Workflow id `create-payout`, exported as `createPayoutWorkflowId`.
+
+```ts
+const { result } = await createPayoutWorkflow(container).run({
+  input: { order_id: "order_01JD8Q1234567" },
+})
+```
+
+Steps, in order:
+
+1. `fetch-order`: loads `total`, `currency_code`, `seller.payout_account`, items, and shipping methods
+2. `fetch-commission-lines`: loads the `commission_line` rows for those items and shipping methods
+3. `create-payout-step`: creates the payout for `total` minus the commission sum, with the order id as `context.idempotency_key`
+4. `create-remote-links`: links the payout to the seller
+
+It throws `Seller does not have a payout account` when the seller has none. Returns the `PayoutDTO`.
+
+| Hook | Payload | Use it to |
+| --- | --- | --- |
+| `payoutCreated` | `{ order_id, payout_id }` | Link the payout to the order, notify the seller, or sync a ledger |
+
+## processPayoutForWebhookWorkflow
+
+Applies a parsed provider webhook to an account or a payout. Workflow id `process-payout-for-webhook`, exported as `processPayoutForWebhookWorkflowId`. Its input is a `PayoutWebhookResult`: an `action` and an optional `data.id`.
+
+| Action | Step name | Effect |
 | --- | --- | --- |
-| `createPayoutAccountWorkflow` | `{ seller_id, data?, context? }` | Create a payout account, call the provider, link it to the store |
-| `createOnboardingWorkflow` | `{ account_id, data?, context? }` | Create or update the account's onboarding record via the provider |
+| `account.activated` | `activate-payout-account` | Account `status` to `active` |
+| `account.restricted` | `restrict-payout-account` | Account `status` to `restricted` |
+| `account.rejected` | `reject-payout-account` | Account `status` to `rejected` |
+| `payout.processing` | `processing-payout` | Payout `status` to `processing` |
+| `payout.paid` | `paid-payout` | Payout `status` to `paid` |
+| `payout.failed` | `failed-payout` | Payout `status` to `failed` |
+| `payout.canceled` | `canceled-payout` | Payout `status` to `canceled` |
 
-## Payout workflows
+Each branch runs only when `data.id` is set. `not_supported` runs no step. Returns nothing and exposes no hooks.
 
-| Workflow | Input | Purpose |
+## Steps
+
+You can compose these steps into your own workflows:
+
+| Step | Id | Compensation |
 | --- | --- | --- |
-| `createPayoutWorkflow` | `{ order_id }` | Compute the seller's share (total − commission) and initiate a transfer |
-| `processPayoutForWebhookWorkflow` | `PayoutWebhookResult` | Apply a provider webhook to account or payout status |
+| `validateSellerPayoutAccountStep` | `validate-seller-payout-account` | None |
+| `createPayoutAccountStep` | `create-payout-account` | None |
+| `createOnboardingStep` | `create-onboarding` | None |
+| `createPayoutStep` | `create-payout-step` | None |
+| `updatePayoutAccountStep` | `update-payout-account-step` | Restores the previous status |
+| `updatePayoutStep` | `update-payout-step` | Restores the previous status |
 
 <Note>
-  `createPayoutWorkflow` reads the order with its seller, payout account, and
-  commission lines, then uses the order id as the transfer's idempotency key so
-  a re-run never double-pays.
+  The create steps have no compensation. If a later step fails, the account, onboarding record, or payout stays, and the provider-side object stays too. The service only deletes a new row when the provider call itself throws.
 </Note>
-
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/payout/reference/service). For the events that
-drive these workflows, see the [Event reference](/platform/payout/reference/events).

package/content/platform/product-edit/concepts/change-actions.mdx

@@ -1,66 +1,73 @@
 ---
-title: "Change actions"
+title: "What a change action records and how it applies"
 sidebarTitle: "Change actions"
-description: "The typed actions that make up a change and the details they carry."
+description: "The ProductChangeAction types, the details each one carries, and the order they apply in."
 ---
 
-In this document, you'll learn how the individual operations inside a change are
-modeled.
+A change action is one operation inside a product change: set a field, add a variant, detach an attribute, delete the product. Splitting a change into typed actions lets an operator see exactly what a seller asked for, and lets Mercur apply each operation through the right Medusa workflow when the change is confirmed.
 
-## Product change action
+## The action record
 
-Each operation inside a change is a `ProductChangeAction` (table
-`product_change_action`, id prefix `prodchact`). An action belongs to a parent
-`ProductChange`, targets a `product_id`, and names the operation in its `action`
-field. The operation's payload lives in the `details` JSON, and an `applied`
-boolean records whether it has already been written to the product.
+A `ProductChangeAction` (id prefix `prodchact`) belongs to a parent change through `product_change_id` and targets a `product_id`. Its `action` field names the operation, and its `details` JSON holds the payload. The `applied` boolean starts `false` and flips to `true` once the action has been written to the product.
+
+Actions also carry an auto-incrementing `ordering`, plus `reference` and `reference_id` columns. Mercur’s workflows don’t set the reference columns, so you can use them to point an action at a record of your own.
 
 ```ts
 const action = {
-  product_id: "prod_123",
-  action: "UPDATE",
-  details: { field: "title", value: "New title" },
+  product_id: "prod_01JD8Q1234567",
+  action: ProductChangeActionType.UPDATE,
+  details: { field: "title", value: "Linen shirt" },
 }
 ```
 
-Actions carry an autoincrementing `ordering` so a change with several operations
-applies them deterministically.
+This is the shape you pass to `stageProductChangeWorkflow` in its `actions` array. `ProductChangeActionType` is exported from `@mercurjs/types`.
 
 ## Action types
 
-The `action` field is one of the `ProductChangeActionType` values. Each type
-reads a different shape out of `details`:
+The `action` field takes one of the 11 `ProductChangeActionType` values. The edit workflows also store the previous value in `details`, so a reviewer can see the before and after:
 
-| Action | `details` shape | Applies |
+| Action | `details` written by Mercur | Applies |
 | --- | --- | --- |
-| `UPDATE` | `{ field, value }` | A single product field update |
-| `STATUS_CHANGE` | `{ status }` | A product status change |
-| `VARIANT_ADD` | `{ variant }` | Create a variant |
-| `VARIANT_UPDATE` | `{ variant_id, fields }` | Update a variant (scalars + image links) |
-| `VARIANT_REMOVE` | `{ variant_id }` | Delete a variant |
-| `ATTRIBUTE_ADD` | `{ attribute }` | Attach a product attribute |
-| `ATTRIBUTE_UPDATE` | `{ update }` | Change an attached attribute |
-| `ATTRIBUTE_REMOVE` | `{ attribute_id }` | Detach an attribute |
-| `PRODUCT_ADD` | None | Record a product creation in the trail |
-| `PRODUCT_DELETE` | None | Delete the product |
-| `CHANGE_REQUESTED` | `{ message }` | Record an operator revision request |
-
-<Note>
-  `CHANGE_REQUESTED` mutates nothing. It's an audit-only marker for a revision
-  request. The operator's message rides on both the action's `details.message`
-  and the parent change's `external_note`. See
-  [Status & auto-confirm](/platform/product-edit/concepts/status-and-auto-confirm).
-</Note>
+| `UPDATE` | `{ field, value, previous_value }` | Sets one product field |
+| `STATUS_CHANGE` | `{ status, previous_status }` | Sets the product status |
+| `VARIANT_ADD` | `{ variant }` | Creates a variant |
+| `VARIANT_UPDATE` | `{ variant_id, fields, previous_fields }` | Updates a variant and its image links |
+| `VARIANT_REMOVE` | `{ variant_id }` | Deletes a variant |
+| `ATTRIBUTE_ADD` | `{ attribute, attribute_id, previous_value }` | Attaches an attribute |
+| `ATTRIBUTE_UPDATE` | `{ update, attribute_id, value, previous_value }` | Changes an attached attribute |
+| `ATTRIBUTE_REMOVE` | `{ attribute_id, previous_value }` | Detaches an attribute |
+| `PRODUCT_DELETE` | `{}` | Deletes the product and its offers |
+| `PRODUCT_ADD` | `{ status, attribute_ids }` | Nothing: records the product’s creation |
+| `CHANGE_REQUESTED` | `{ message }` | Nothing: records a revision request |
+
+`PRODUCT_ADD` and `CHANGE_REQUESTED` only appear on audit changes, which Mercur stores with `applied: true`. See [The change pipeline](/platform/product-edit/concepts/change-pipeline#audit-changes).
+
+## What the edit workflows diff
+
+The edit workflows stage an action only when your input differs from the product. Arrays of relations compare by id or URL, ignoring order, so resending the same categories stages nothing:
+
+- **Product fields**: `title`, `subtitle`, `handle`, `description`, `discountable`, `is_giftcard`, `thumbnail`, `images`, `material`, `weight`, `length`, `height`, `width`, `hs_code`, `mid_code`, `origin_country`, `type_id`, `collection_id`, `categories`, `tags`, `sales_channels`, `metadata`
+- **Status**: a `status` key in the update becomes a `STATUS_CHANGE` action instead of an `UPDATE`
+- **Variants**: `manage_inventory` is skipped on update, and `images` takes `{ add, remove }` image ids
+- **Attributes**: an add the product already holds, or a remove of an attribute it doesn’t hold, stages nothing
+
+A key outside the product field list is ignored by `productEditUpdateProductWorkflow`.
 
 ## How actions apply
 
-When a change is confirmed, its **not-yet-applied** actions are bucketed by type
-and dispatched to the matching Medusa workflows in one pass: product updates,
-variant creates/updates/deletes, and the attribute batch. Each action is then
-flipped to `applied: true` so a re-run never applies it twice.
+When a change is confirmed, `applyProductChangeActionsWorkflow` loads its actions with `applied: false`, groups them by type, and runs each group once. The groups run in this order:
+
+1. `STATUS_CHANGE` and `UPDATE`, merged per product into one `updateProductsWorkflow` call
+2. `VARIANT_REMOVE` through `deleteProductVariantsWorkflow`
+3. `VARIANT_ADD` through `createProductVariantsWorkflow`
+4. `VARIANT_UPDATE` scalar fields through `updateProductVariantsWorkflow`, then the variant image links
+5. `ATTRIBUTE_*` as one batch through `createAndLinkProductAttributesToProductWorkflow`
+6. `PRODUCT_DELETE` through `deleteProductsWorkflow`, followed by `deleteOffersWorkflow` for the product’s offers
+
+The workflow then marks every action it handled as `applied: true`, so running the apply workflow again on the same change never writes an action twice. Types it doesn’t handle, `PRODUCT_ADD` and `CHANGE_REQUESTED`, keep whatever `applied` value they were stored with.
+
+## Related
 
-<Tip>
-  Audit-trail changes (publish approvals, revision requests) are stored with
-  their actions already `applied`, so confirming them is a no-op on the product
-  itself. They exist purely as history.
-</Tip>
+- [The change lifecycle and auto-confirm](/platform/product-edit/concepts/status-and-auto-confirm)
+- [Stage actions directly](/platform/product-edit/guides/edit-a-product#stage-actions-directly)
+- [The `ProductChangeAction` data model](/platform/product-edit/reference/data-models#productchangeaction)

package/content/platform/product-edit/concepts/change-pipeline.mdx

@@ -1,69 +1,77 @@
 ---
-title: "The change pipeline"
+title: "How product changes are staged and recorded"
 sidebarTitle: "The change pipeline"
-description: "The ProductChange record, its immutability, and the audit trail."
+description: "How an edit becomes a ProductChange, who can have one open, and how the audit trail builds up."
 ---
 
-In this document, you'll learn how a product edit is captured and why the
-pipeline is built on immutable records.
+A product change is one reviewable edit to one product. Because every seller sells against the same shared product, a seller’s edit can’t take effect the moment it’s made. Mercur stores the edit as a `ProductChange` with its actions, holds it for review, and applies it only on confirmation. The same records double as the product’s history.
 
-## Product change
+## The product change record
 
-A product change is a single reviewable edit to one product, represented by the
-`ProductChange` data model (table `product_change`, id prefix `prodch`). It
-references the target product through `product_id`, carries the `status` of the
-review, and records who created and resolved it (`created_by`, `confirmed_by`,
-`declined_by`, `canceled_by`) with matching timestamps.
+A `ProductChange` (id prefix `prodch`) points at its product through `product_id` and carries a `status` from the `ProductChangeStatus` enum. It owns one or more `ProductChangeAction` rows in `actions`, one per operation it will apply. The change is the unit you review. The actions are what gets written.
+
+Each resolution stamps an actor and a time on the record:
+
+- **Staging**: `created_by`
+- **Confirm**: `confirmed_by`, `confirmed_at`
+- **Decline**: `declined_by`, `declined_at`, `declined_reason`
+- **Cancel**: `canceled_by`, `canceled_at`
+
+The actor fields are plain text. Vendor routes write the seller id (`sel_…`) into `created_by`, and admin routes write the operator’s user id. Two notes travel with the change: `internal_note` for operators and `external_note` for the seller.
 
 ```ts
-const productChangeModuleService = container.resolve(MercurModules.PRODUCT_EDIT)
+import { MercurModules } from "@mercurjs/types"
 
-const change = await productChangeModuleService.retrieveProductChange(id, {
-  relations: ["actions"],
-})
+const productEdit = container.resolve(MercurModules.PRODUCT_EDIT)
+
+const change = await productEdit.retrieveProductChange(
+  "prodch_01JD8Q1234567",
+  { relations: ["actions"] }
+)
 ```
 
-A change owns one or more `ProductChangeAction` records (`actions`). The change
-is the reviewable unit; the actions are the individual operations it will apply.
-See [Change actions](/platform/product-edit/concepts/change-actions).
+The service call loads one change with its actions. To read a product’s full history, use the `product.changes` link instead, covered in [Links](/platform/product-edit/reference/links).
 
-<Note>
-  A product can have **only one active (pending) change at a time**. Staging a
-  new change while one is still pending is rejected. The vendor resolves or
-  cancels the open change first.
-</Note>
+## How an edit is staged
 
-## Immutability & the audit trail
+Seller edits reach the pipeline through four edit workflows. Each one loads the current product, compares your input against it, and passes only the differences to `stageProductChangeWorkflow`:
 
-A change is never rewritten in place. It is created, its actions are appended,
-and it is resolved by moving `status` forward and stamping the actor and time.
-Because nothing is overwritten, the set of `ProductChange` rows on a product is a
-durable history of who changed what and who approved it.
+- **`productEditUpdateProductWorkflow`**: product fields and status, as `UPDATE` and `STATUS_CHANGE` actions
+- **`productEditUpdateVariantsWorkflow`**: variant add, update, and remove operations, as `VARIANT_*` actions
+- **`productEditUpdateAttributesWorkflow`**: attribute add, update, and remove, as `ATTRIBUTE_*` actions
+- **`productEditDeleteProductWorkflow`**: a single `PRODUCT_DELETE` action
 
-Some events aren't vendor edits at all, such as a publish approval or a revision
-request. They still belong in the history. Those are recorded as changes created
-already `confirmed`, so the audit trail captures them without waiting on review.
+`stageProductChangeWorkflow` creates the `pending` change, creates its actions, emits `product-change.created`, and then runs `autoConfirmProductChangeWorkflow`. Whether the change confirms in that same run is covered in [Status & auto-confirm](/platform/product-edit/concepts/status-and-auto-confirm).
 
-```ts
-await recordProductAuditChangeWorkflow(container).run({
-  input: {
-    actor_id: "user_123",
-    changes: [
-      {
-        product_id: "prod_123",
-        external_note: "Approved for publish",
-        actions: [
-          { product_id: "prod_123", action: "STATUS_CHANGE", details: { status: "published" } },
-        ],
-      },
-    ],
-  },
-})
-```
+## One open change per author
+
+The edit workflows and `createProductChangeWorkflow` refuse to stage a change when the same author already has a `pending` change on that product. The check is scoped by `created_by`, so two different sellers can each have one open change on the same shared product. When `created_by` is missing, the check covers every pending change on the product.
+
+<Warning>
+  `stageProductChangeWorkflow` doesn’t run this check. Call it directly only when you’ve handled conflicts yourself, or prefer an edit workflow.
+</Warning>
+
+The conflict surfaces as a `NOT_ALLOWED` error: “There is already an active update request for this product. Only one request can be active at a time.” The author resolves it by canceling the open change or waiting for an operator to resolve it.
+
+## Audit changes
+
+Some events change a product without a review, yet still belong in its history. `recordProductAuditChangeWorkflow` stores them as changes created already `confirmed`, with every action marked `applied`, so confirming never replays them. Mercur’s product workflows call it in four places:
+
+| Workflow | Action recorded | `details` |
+| --- | --- | --- |
+| `createProductsWorkflow` | `PRODUCT_ADD` | `{ status, attribute_ids }` |
+| `confirmProductsWorkflow` | `STATUS_CHANGE` | `{ status: "published" }` |
+| `rejectProductWorkflow` | `STATUS_CHANGE` | `{ status: "rejected" }` |
+| `requestProductChangeWorkflow` | `CHANGE_REQUESTED` | `{ message }` |
+
+The `PRODUCT_ADD` record does real work: its `created_by` is the seller who submitted the product, and the vendor API reads it to tell which products a seller created.
+
+<Note>
+  Operator edits through the admin product update route run Medusa’s `updateProductsWorkflow` directly and don’t create a change. The pipeline governs seller edits.
+</Note>
+
+## Related
 
-<Tip>
-  Read a product's full history through the read-only `product.changes` link
-  (see the [Links reference](/platform/product-edit/reference/links)) rather than
-  querying the module directly. The link keeps the audit trail attached to the
-  product.
-</Tip>
+- [The action types and their `details`](/platform/product-edit/concepts/change-actions)
+- [Statuses, revision requests, and auto-confirm](/platform/product-edit/concepts/status-and-auto-confirm)
+- [Stage an edit from your own route](/platform/product-edit/guides/edit-a-product)

package/content/platform/product-edit/concepts/status-and-auto-confirm.mdx

@@ -1,66 +1,63 @@
 ---
-title: "Status & auto-confirm"
+title: "Change statuses, revision requests, and auto-confirm"
 sidebarTitle: "Status & auto-confirm"
-description: "The change status lifecycle, revision requests, and auto-confirm."
+description: "The four ProductChangeStatus values, how a revision request fits in, and when a change confirms without review."
 ---
 
-In this document, you'll learn about the states a change moves through and when
-it resolves without operator review.
+Every product change has a status that says whether it’s waiting for review or already resolved. A change starts `pending` and is resolved exactly once: confirmed, declined, or canceled. Whether a seller’s edit waits for an operator at all depends on the `product_request` feature flag and on the `auto_confirm` input.
 
-## Status
+## The status lifecycle
 
-A change's state is held in the `status` field of the `ProductChange` model,
-typed by the `ProductChangeStatus` enum. A change moves through four statuses:
+The `status` field takes one of the four `ProductChangeStatus` values, exported from `@mercurjs/types`. Each resolution has its own workflow, which checks that the change is still `pending`, stamps the actor field, and emits an event.
 
-```
-                ┌───────────┐
-                │  pending   │
-                └─────┬─────┘
-          ┌───────────┼───────────┐
-    confirm          decline     cancel
-          ▼           ▼           ▼
-   ┌───────────┐ ┌──────────┐ ┌──────────┐
-   │ confirmed │ │ declined │ │ canceled │
-   └───────────┘ └──────────┘ └──────────┘
-```
+<img className="block dark:hidden" src="/images/figures/product-edit-lifecycle-light.svg" alt="The ProductChangeStatus table: a change enters pending through stageProductChangeWorkflow, then confirmProductChangeWorkflow, rejectProductChangeWorkflow, or cancelProductChangeWorkflow moves it to confirmed, declined, or canceled, each emitting its own event and stamping its own actor field." />
+<img className="hidden dark:block" src="/images/figures/product-edit-lifecycle-dark.svg" alt="The ProductChangeStatus table: a change enters pending through stageProductChangeWorkflow, then confirmProductChangeWorkflow, rejectProductChangeWorkflow, or cancelProductChangeWorkflow moves it to confirmed, declined, or canceled, each emitting its own event and stamping its own actor field." />
+
+| Status | Meaning | Product touched |
+| --- | --- | --- |
+| `pending` | Staged and waiting for review. The default | No |
+| `confirmed` | Approved, or recorded as an audit change | Yes, its actions are applied |
+| `declined` | Rejected by an operator, with an optional `declined_reason` | No |
+| `canceled` | Withdrawn, by the seller or an operator, before review | No |
 
-| Status | Meaning |
-| --- | --- |
-| `pending` | Awaiting operator review. The default for a staged edit |
-| `confirmed` | Approved; its actions are applied to the product |
-| `declined` | Rejected by the operator; nothing is applied |
-| `canceled` | Withdrawn (e.g. by the vendor) before review |
+Confirming, declining, or canceling a change that isn’t `pending` fails with a `NOT_ALLOWED` error. Each resolution step saves the previous values, so if a later step fails, the workflow restores the change to `pending`.
 
 <Note>
-  Only a `pending` change can be confirmed, declined, or canceled. The
-  resolution workflows validate the current status first, so a change is
-  resolved exactly once.
+  The model also has `requires_action_by`, `requires_action_at`, and `requires_action_reason` columns, but `ProductChangeStatus` has no `requires_action` value and no workflow writes those columns.
 </Note>
 
 ## Revision requests
 
-When an operator wants a submission reworked rather than approved or rejected,
-they **request a revision**. This is recorded as a `CHANGE_REQUESTED` audit
-action (a `confirmed` audit change) carrying the operator's message, and it emits
-`product.change-requested`. The product stays with the vendor to revise and
-resubmit. A revision request is a signal in the audit trail, not a fourth
-resolution of the pending change.
+A revision request sends a proposed product back to its seller without approving or rejecting it. `requestProductChangeWorkflow` checks that the product status is `proposed`, records an audit change with a `CHANGE_REQUESTED` action, and emits `product.change-requested`. The product stays `proposed` for the seller to revise.
+
+A revision request isn’t a fifth status, and it doesn’t resolve any pending change. It’s an already-`confirmed` entry in the product’s history. The operator’s message is stored twice: in the action’s `details.message` and in the change’s `external_note`.
 
 ## Auto-confirm
 
-Staging a change runs `autoConfirmProductChangeWorkflow`. Whether it confirms
-immediately depends on the marketplace's review setting:
+Staging always runs `autoConfirmProductChangeWorkflow` right after the change is created. It runs `confirmProductChangeWorkflow` in the same workflow run when either condition holds:
+
+- **The flag is off**: the `product_request` feature flag is disabled
+- **Forced**: the caller passed `auto_confirm: true`, which reaches the workflow as `force`
+
+Otherwise the change stays `pending`. The flag is on by default. Turn it off with an environment variable:
+
+```bash title=".env"
+MEDUSA_FF_PRODUCT_REQUEST=false
+```
+
+With the flag off, every seller edit applies immediately and still leaves a confirmed change in the trail. The same flag also controls product creation: while it’s on, a seller can only create products as `draft` or `proposed`.
+
+## When Mercur forces auto-confirm
+
+There’s no risk scoring: Mercur doesn’t classify edits as low or high risk. It forces auto-confirm in two places:
+
+- **Draft deletes**: `productEditDeleteProductWorkflow` defaults `auto_confirm` to `true` when the product is a `draft`
+- **Operator deletes**: the admin product delete route always passes `auto_confirm: true`
 
-- **Review off:** the change is confirmed and applied in the same run, so
-  low-friction edits don't wait for an operator.
-- **Review on:** the change stays `pending` for an operator to resolve.
+An auto-confirmed change goes through the same `confirmProductChangeWorkflow` as a manual approval. It emits `product-change.confirmed` and fires the same hooks, with `confirmed_by` set to the change’s author.
 
-You can also force auto-confirm for a specific change (for example a
-trusted-source import) via the `auto_confirm` flag on the staging workflow,
-regardless of the review setting.
+## Related
 
-<Tip>
-  Auto-confirm reuses the exact same `confirmProductChangeWorkflow` as a manual
-  approval, so an auto-confirmed change is applied and audited identically to one
-  an operator approves by hand.
-</Tip>
+- [Confirm, decline, or cancel a change in code](/platform/product-edit/guides/confirm-or-decline-a-change)
+- [Request a revision](/platform/product-edit/guides/request-a-revision)
+- [The events each transition emits](/platform/product-edit/reference/events)