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

package/content/platform/commission/reference/data-models.mdx

@@ -1,75 +1,89 @@
 ---
-title: "Data models"
+title: "Commission data models"
 sidebarTitle: "Data models"
-description: "The data models owned by the Commission domain."
+description: "Every field of CommissionRate, CommissionRule, CommissionRateValue, and CommissionLine."
 ---
 
-The Commission domain is owned by the **Commission module**. This reference
-lists its data models and their fields. For the full module overview, see the
-[Commission overview](/platform/commission/overview).
+The Commission module owns four data models, defined in `packages/core/src/modules/commission/models`. Every model also has `created_at`, `updated_at`, and a nullable `deleted_at`, which Medusa adds and the tables below leave out.
 
 ## CommissionRate
 
-Table `commission_rate`, id prefix `comrate`. The rate the marketplace takes
-from a sale.
+The rate the marketplace takes from a sale. Table `commission_rate`, id prefix `comrate`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
 | `id` | text | Primary key |
-| `name` | text | Searchable |
-| `code` | text | Unique, searchable; auto-generated from `name` when omitted |
-| `type` | enum | `CommissionRateType`, `fixed` or `percentage` |
-| `value` | bigNumber | Percent (for `percentage`) or fallback amount (for `fixed`) |
-| `currency_code` | text | Nullable; when set, the rate applies only to that currency |
-| `include_tax` | boolean | Default `false`; add `tax_total` to the base amount |
-| `include_shipping` | boolean | Default `false`; only meaningful on the global rate |
-| `is_enabled` | boolean | Default `true`; only enabled rates are evaluated |
-| `is_default` | boolean | Default `false`; the single Global Commission |
-
-Relations: `rules` (one-to-many `CommissionRule`), `values` (one-to-many
-`CommissionRateValue`).
+| `name` | text | Display name, searchable |
+| `code` | text | Unique among non-deleted rates and searchable. Generated from `name` when omitted on create |
+| `type` | enum | `CommissionRateType`: `fixed` or `percentage` |
+| `value` | bigNumber | The percent for `percentage`, the fallback amount for `fixed` |
+| `currency_code` | text, nullable | When set, the rate applies only to orders in this currency |
+| `include_tax` | boolean | Default `false`. Adds the line’s `tax_total` to the base amount |
+| `include_shipping` | boolean | Default `false`. Produces shipping lines, on the `is_default` rate only |
+| `is_enabled` | boolean | Default `true`. Disabled rates are skipped |
+| `is_default` | boolean | Default `false`. Marks the global commission, which can’t be deleted |
+
+Relations:
+
+- **`rules`**: has many `CommissionRule`
+- **`values`**: has many `CommissionRateValue`
 
 ## CommissionRule
 
-Table `commission_rule`, id prefix `comrule`. Scopes a rate to a slice of the
-catalog.
+Scopes a rate to one record in one dimension. Table `commission_rule`, id prefix `comrule`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
 | `id` | text | Primary key |
 | `reference` | text | The dimension: `product`, `product_type`, `product_collection`, `product_category`, or `seller` |
 | `reference_id` | text | The id of the record in that dimension |
-| `commission_rate` | relation | The rate this rule belongs to (`belongsTo`) |
+| `commission_rate_id` | text | Foreign key to the owning rate |
+
+Relations:
+
+- **`commission_rate`**: belongs to `CommissionRate`
+
+The table has an index on `(reference, reference_id)` for non-deleted rows.
 
 ## CommissionRateValue
 
-Table `commission_rate_value`, id prefix `comval`. A per-currency amount for a
-fixed rate.
+A per-currency amount for a fixed rate. Table `commission_rate_value`, id prefix `comval`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
 | `id` | text | Primary key |
-| `currency_code` | text | The currency this amount applies to |
-| `amount` | bigNumber | The flat commission for that currency |
-| `commission_rate` | relation | The rate this value belongs to (`belongsTo`) |
+| `currency_code` | text | The currency this amount applies to, such as `usd` |
+| `amount` | bigNumber | The fixed commission per line item in that currency |
+| `commission_rate_id` | text | Foreign key to the owning rate |
+
+Relations:
+
+- **`commission_rate`**: belongs to `CommissionRate`
 
 ## CommissionLine
 
-Table `commission_line`, id prefix `comline`. The resolved commission for one
-order line.
+The resolved commission for one order line item or shipping method. Table `commission_line`, id prefix `comline`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
 | `id` | text | Primary key |
-| `item_id` | text | Nullable; the order line item this line commissions |
-| `shipping_method_id` | text | Nullable; the shipping method this line commissions |
-| `commission_rate_id` | text | Nullable; the rate that matched |
-| `code` | text | The matched rate's code |
-| `rate` | float | The applied rate |
-| `amount` | bigNumber | The computed commission amount |
-| `description` | text | Nullable; `"Shipping Commission"` on shipping lines |
-
-<Note>
-  A commission line anchors to **either** `item_id` **or** `shipping_method_id`.
-  It references those records by id, not through a module link.
-</Note>
+| `item_id` | text, nullable | The order line item this line commissions |
+| `shipping_method_id` | text, nullable | The order shipping method this line commissions |
+| `commission_rate_id` | text, nullable | The rate that produced the line. Plain text, not a relation |
+| `provider_id` | text | Default `system`. The provider that computed the line |
+| `code` | text | The code of the rate that produced the line |
+| `rate` | float | The percent, or the fixed amount, that was applied |
+| `amount` | bigNumber | The commission amount |
+| `description` | text, nullable | `Shipping Commission` on shipping lines from the `system` provider |
+| `data` | json, nullable | Free data from the provider |
+
+The table has indexes on `item_id` and on `shipping_method_id` for non-deleted rows. A line sets one of the two anchors and leaves the other `null`.
+
+## Enums
+
+`CommissionRateType` is exported from `@mercurjs/types`.
+
+| Member | Value |
+| --- | --- |
+| `CommissionRateType.FIXED` | `fixed` |
+| `CommissionRateType.PERCENTAGE` | `percentage` |

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

@@ -1,58 +1,52 @@
 ---
-title: "Event reference"
+title: "Commission events"
 sidebarTitle: "Events"
-description: "How the Commission domain stays in sync with order changes."
+description: "Commission emits no domain events of its own. It listens to four order events and recomputes commission lines."
 ---
 
-The Commission domain does **not** emit its own domain events. Commission lines
-are derived data, so instead of broadcasting changes, the module **subscribes**
-to order lifecycle events and recomputes lines whenever an order's composition
-changes.
+The Commission module doesn’t define or emit domain events. Commission lines are derived from the order, so the module listens to order events instead and recomputes the lines when the order’s contents change.
 
-## Events it reacts to
+## Events that trigger a recompute
 
-Mercur ships a subscriber (`order-commission-refresh-handler`) that re-runs
-`refreshOrderCommissionLinesWorkflow` for the affected order on each of these
-events:
+The `order-commission-refresh-handler` subscriber, in `packages/core/src/subscribers/order-edit-confirmed.ts`, runs `refreshOrderCommissionLinesWorkflow` for the order on each of these events.
 
-| Event | Emitted when |
-| --- | --- |
-| `OrderEditWorkflowEvents.CONFIRMED` | An order edit is confirmed |
-| `OrderWorkflowEvents.RETURN_RECEIVED` | A return is received |
-| `OrderWorkflowEvents.CLAIM_CREATED` | A claim is created |
-| `OrderWorkflowEvents.EXCHANGE_CREATED` | An exchange is created |
+| Event | Emitted when | Payload the subscriber reads |
+| --- | --- | --- |
+| `order-edit.confirmed` | An order edit is confirmed | `order_id` |
+| `order.return_received` | A return is received | `order_id` |
+| `order.claim_created` | A claim is created | `order_id` |
+| `order.exchange_created` | An exchange is created | `order_id` |
 
-Because the refresh is idempotent (delete-then-insert), reacting to several
-events for the same order never duplicates lines.
+The subscriber reads `order_id` and falls back to `id`. It does nothing when the payload has neither. The events come from Medusa as `OrderEditWorkflowEvents.CONFIRMED`, `OrderWorkflowEvents.RETURN_RECEIVED`, `OrderWorkflowEvents.CLAIM_CREATED`, and `OrderWorkflowEvents.EXCHANGE_CREATED`.
 
-## Run your own side effects
+Checkout doesn’t go through an event. `completeCartWithSplitOrdersWorkflow` runs the refresh as a nested step for every seller order it creates.
 
-To run logic when an order's commission changes, subscribe to the same order
-events the module listens to, then read the refreshed lines from the commission
-module.
+## Run your own logic after a recompute
 
-```ts title="src/subscribers/commission-changed.ts"
+Subscribe to the same order events to run your own logic when an order’s commission may change.
+
+```ts title="src/subscribers/commission-audit.ts"
 import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
 import { OrderWorkflowEvents } from "@medusajs/framework/utils"
 
-export default async function commissionChangedHandler({
+export default async function commissionAudit({
   event,
   container,
-}: SubscriberArgs<{ order_id?: string; id?: string }>) {
-  const orderId = event.data.order_id ?? event.data.id
-  if (!orderId) {
-    return
-  }
-  // ...read commission lines for the order, notify, sync an external ledger, etc.
+}: SubscriberArgs<{ order_id: string }>) {
+  const logger = container.resolve("logger")
+  logger.info(`Commission may have changed on ${event.data.order_id}`)
 }
 
 export const config: SubscriberConfig = {
-  event: OrderWorkflowEvents.RETURN_RECEIVED,
+  event: [
+    OrderWorkflowEvents.RETURN_RECEIVED,
+    OrderWorkflowEvents.CLAIM_CREATED,
+  ],
 }
 ```
 
+Subscribers run independently, so this one can run before the refresh finishes. When you need the new lines, use the `commissionLinesUpserted` hook of `refreshOrderCommissionLinesWorkflow`, which runs after they’re written. See [Refresh order commission lines](/platform/commission/guides/refresh-order-commission-lines).
+
 <Note>
-  Commission is also refreshed at checkout, as each per-seller order is created
-  from the split cart. That refresh happens as a **step inside** the checkout
-  workflow rather than via a separate event.
+  Like every `MedusaService` module, the Commission service also emits Medusa’s internal data-mutation events when records are created, updated, or deleted. Mercur doesn’t subscribe to them, and this reference doesn’t treat them as a stable contract.
 </Note>

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

@@ -1,45 +1,54 @@
 ---
-title: "Links to other modules"
+title: "Commission links to other modules"
 sidebarTitle: "Links"
-description: "How the Commission domain connects to the catalog, sellers, and orders."
+description: "Commission defines no module links. Rules and lines reference the catalog, sellers, and orders by plain id."
 ---
 
-Most Mercur modules connect to each other through **module links** (`defineLink`)
-resolved with `query.graph`. The Commission module is deliberately different: it
-defines **no** module links. Instead it connects to the rest of the marketplace
-through **soft references**. These are plain id fields resolved at calculation
-time. This keeps commission configuration independent of the catalog and order
-modules it scopes against.
+The Commission module defines no module links. None of the files in `packages/core/src/links` has a commission side. Rules and lines point at records in other modules through plain id fields, which Mercur resolves at calculation time or which you filter on directly.
 
-## Rules → catalog & sellers
+## Rules point at the catalog and sellers
 
-A `CommissionRule` points at a record in another domain through its
-`reference` / `reference_id` pair, resolved against the order line's product when
-commission is calculated:
+A `CommissionRule` names its target with `reference` and `reference_id`. The `refreshOrderCommissionLinesWorkflow` reads the target’s fields from the order with `query.graph`, so the commission records never need a link.
 
-| `reference` | Points at | Resolved from |
+| `reference` | Points at | Read from the order line |
 | --- | --- | --- |
-| `product` | A master product | `item.product.id` |
-| `product_type` | A product type | `item.product.type_id` |
-| `product_collection` | A collection | `item.product.collection_id` |
-| `product_category` | A category | `item.product.categories[].id` |
-| `seller` | A store | `item.offer.seller_id` |
+| `product` | A master product | `items.product.id` |
+| `product_type` | A product type | `items.product.type_id` |
+| `product_collection` | A product collection | `items.product.collection_id` |
+| `product_category` | A product category | `items.product.categories.id` |
+| `seller` | A seller | `items.offer.seller_id` |
 
-<Note>
-  Products are the shared master catalog, not seller-owned. The `seller`
-  dimension resolves through the **offer** on the order line, which carries the
-  selling store.
-</Note>
+The `seller` row goes through the `order-line-item-offer-link` from the Offer module. Products belong to the shared catalog, so the seller of a line is the seller of the offer the customer bought.
+
+## Lines point at order items and shipping methods
+
+A `CommissionLine` stores `item_id` or `shipping_method_id` as plain text. To get an order’s lines, collect the ids from the order, then filter `commission_line` by them.
+
+```ts
+const { data: [order] } = await query.graph({
+  entity: "order",
+  fields: ["items.id", "shipping_methods.id"],
+  filters: { id: "order_01JD8Q1234567" },
+})
 
-## Lines → orders
+const { data: lines } = await query.graph({
+  entity: "commission_line",
+  fields: ["item_id", "shipping_method_id", "code", "amount"],
+  filters: {
+    $or: [
+      { item_id: order.items.map((item) => item.id) },
+      { shipping_method_id: order.shipping_methods.map((m) => m.id) },
+    ],
+  },
+})
+```
 
-A `CommissionLine` records which order line it commissions through its
-`item_id` (an order line item) or `shipping_method_id` (a shipping method).
-These are stored as plain ids, so the payout pipeline reads an order's lines by
-querying the commission module directly rather than traversing a link.
+`createPayoutWorkflow` and the order commission-lines routes read lines the same way.
 
-<Tip>
-  Because these are soft references, deleting a product, category, or order does
-  not cascade to commission records. Rules and lines simply stop matching or are
-  refreshed on the next order change.
-</Tip>
+## Lines point at their rate
+
+`commission_rate_id` on a line is also plain text, not a relation. Query the rate separately if you need more than the `code` the line already stores.
+
+<Note>
+  Plain ids don’t cascade. Deleting a product, category, or seller leaves its rules in place, where they stop matching. Deleting a rate soft-deletes it and leaves existing lines untouched.
+</Note>

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

@@ -1,51 +1,126 @@
 ---
-title: "Service reference"
+title: "Commission module service"
 sidebarTitle: "Service"
-description: "The Commission module service and its methods for working with records directly."
+description: "Resolve the Commission module service, its generated and custom methods, and the commission provider interface."
 ---
 
-The Commission 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 Commission module service reads and writes commission records without a workflow. Use it in steps, subscribers, and scheduled jobs, and use the [workflows](/platform/commission/reference/workflows) when you need rollback or the global-rate delete guard.
+
+## Resolve the service
+
+Resolve the service from the container with `MercurModules.COMMISSION`.
 
 ```ts
 import { MercurModules } from "@mercurjs/types"
 
-const commissionModuleService = container.resolve(MercurModules.COMMISSION)
+const commission = container.resolve(MercurModules.COMMISSION)
 
-const [rates, count] = await commissionModuleService.listAndCountCommissionRates(
-  { is_enabled: true }
+const [rates, count] = await commission.listAndCountCommissionRates(
+  { is_enabled: true },
+  { relations: ["rules", "values"] }
 )
 ```
 
+The call returns enabled rates with their rules and per-currency values, plus the total count.
+
 ## Generated methods
 
-Each data model gets a standard set of auto-generated methods. For
-`CommissionRate`:
+The service extends `MedusaService`, so every model gets the standard methods. For `CommissionRate` they are:
 
 | Method | Description |
 | --- | --- |
-| `createCommissionRates(data)` | Create one or more rates (auto-generates `code`) |
-| `retrieveCommissionRate(id, config?)` | Retrieve a rate by id |
-| `listCommissionRates(filters?, config?)` | List rates matching filters |
-| `listAndCountCommissionRates(filters?, config?)` | List rates with a total count |
-| `updateCommissionRates(data)` | Update one or more rates |
-| `deleteCommissionRates(ids)` | Delete one or more rates |
+| `retrieveCommissionRate(id, config?)` | Retrieve one rate |
+| `listCommissionRates(filters?, config?)` | List rates |
+| `listAndCountCommissionRates(filters?, config?)` | List rates with a count |
+| `createCommissionRates(data)` | Create one rate or an array of rates |
+| `updateCommissionRates(data)` | Update rates |
+| `deleteCommissionRates(ids)` | Hard-delete rates |
+| `softDeleteCommissionRates(ids)` | Soft-delete rates |
+| `restoreCommissionRates(ids)` | Restore soft-deleted rates |
+
+The same set exists for `CommissionRule`, `CommissionRateValue`, and `CommissionLine`, for example `listCommissionRules`, `createCommissionRateValues`, and `retrieveCommissionLine`.
 
-The same set exists for every model in the module: `CommissionRule`,
-`CommissionRateValue`, and `CommissionLine` (e.g. `createCommissionRules`,
-`listCommissionRateValues`, `deleteCommissionLines`).
+<Warning>
+  `deleteCommissionRates` doesn’t check for the global rate. Use `deleteCommissionRatesWorkflow` to keep the `is_default` rate safe.
+</Warning>
 
-## Calculation & line methods
+## Custom methods
+
+The service overrides or adds these methods:
 
 | Method | Description |
 | --- | --- |
-| `getCommissionLines(context)` | Resolve the commission lines for a calculation context (items + shipping in a currency), most-specific-wins, without persisting |
-| `upsertCommissionLines(lines)` | Replace lines by anchor (`item_id` / `shipping_method_id`), making refreshes idempotent |
+| `createCommissionRates(data)` | Fills a missing `code` from `name` plus a random suffix, then creates. Returns one rate for one input, an array for an array |
+| `listCommissionRates(filters?, config?)` | Accepts a virtual `scope_type` filter |
+| `listAndCountCommissionRates(filters?, config?)` | Accepts the same `scope_type` filter |
+| `getCommissionLines(context)` | Computes lines for one context with the default provider. Doesn’t persist |
+| `getCommissionLinesBatch(contexts)` | Computes lines for several contexts, one array per context in order. Doesn’t persist |
+| `upsertCommissionLines(lines)` | Deletes existing lines with the same `item_id` or `shipping_method_id`, then inserts `lines` |
 
-<Warning>
-  Prefer [workflows](/platform/commission/reference/workflows) for order-line
-  refreshes and rate deletion. `refreshOrderCommissionLinesWorkflow` builds the
-  calculation context from the order and calls these methods for you;
-  `deleteCommissionRatesWorkflow` validates that a rate is safe to delete first.
-</Warning>
+`getCommissionLines` and `getCommissionLinesBatch` stamp the default provider’s id on any line without a `provider_id`. `getCommissionLinesBatch` falls back to one `getCommissionLines` call per context when the provider has no batch method.
+
+## Filter rates by scope type
+
+`scope_type` filters rates by the dimensions their rules use, computed in the database. Pass one value, an array, or a comma-separated string. Several values are combined with OR, and an unknown value matches nothing.
+
+| `scope_type` | Rates whose rules use |
+| --- | --- |
+| `store` | `seller` only, without `product_type` or `product_category` |
+| `product_type` | `product_type`, without `seller` or `product_category` |
+| `category` | `product_category`, without `seller` or `product_type` |
+| `store_product_type` | `seller` and `product_type` |
+| `store_category` | `seller` and `product_category`, without `product_type` |
+
+## Commission providers
+
+A provider computes the lines from a calculation context. The module always registers the built-in `system` provider, which implements the [rule matching](/platform/commission/concepts/rule-matching) algorithm, and uses it unless you configure another one.
+
+```ts title="src/modules/tiered-commission/service.ts"
+import { MathBN } from "@medusajs/framework/utils"
+import type {
+  CommissionCalculationContext,
+  CreateCommissionLineDTO,
+  ICommissionProvider,
+} from "@mercurjs/types"
+
+export default class TieredCommissionProvider
+  implements ICommissionProvider
+{
+  static identifier = "tiered"
+
+  async getCommissionLines(
+    context: CommissionCalculationContext
+  ): Promise<CreateCommissionLineDTO[]> {
+    const percent = context.additional_context?.tier === "gold" ? 8 : 12
+    return (context.items ?? []).map((item) => ({
+      item_id: item.id,
+      code: "tiered",
+      rate: percent,
+      amount: MathBN.div(MathBN.mult(item.subtotal, percent), 100).toNumber(),
+    }))
+  }
+}
+```
+
+A provider class needs a static `identifier` and `getCommissionLines`. It can add `getCommissionLinesBatch(contexts)` to load its data once per batch. The module doesn’t cap `amount`, so keep it within the item’s `total` yourself.
+
+Export the class as a module provider so the commission module can register it.
+
+```ts title="src/modules/tiered-commission/index.ts"
+import { ModuleProvider } from "@medusajs/framework/utils"
+import { MercurModules } from "@mercurjs/types"
+import TieredCommissionProvider from "./service"
+
+export default ModuleProvider(MercurModules.COMMISSION, {
+  services: [TieredCommissionProvider],
+})
+```
+
+The module takes these options, typed as `CommissionModuleOptions`:
+
+| Option | Description |
+| --- | --- |
+| `providers` | Array of `{ resolve, id, options?, is_default? }` registered next to `system` |
+| `default_provider` | Provider id used for every calculation. Overrides `is_default` |
+
+A single configured provider becomes the default without `is_default`.

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

@@ -1,40 +1,114 @@
 ---
-title: "Workflows"
+title: "Commission workflows"
 sidebarTitle: "Workflows"
-description: "Commission rate, rule, and order-line workflows."
+description: "Inputs, outputs, steps, and hooks of the rate, rule, and order-line commission workflows."
 ---
 
-This reference lists the workflows for the Commission domain. Import them from
-`@mercurjs/core/workflows` and run them against the Medusa container.
+The Commission module ships five workflows, exported from `@mercurjs/core/workflows`. They run against the Medusa container, and each step compensates on failure unless noted. None of them emits an event.
 
-## Rate workflows
+## createCommissionRatesWorkflow
 
-| Workflow | Input | Purpose |
+Creates one or more commission rates. Workflow id `create-commission-rates`.
+
+| Input | Type |
+| --- | --- |
+| (root) | `CreateCommissionRateDTO[]` |
+
+`CreateCommissionRateDTO` takes `name`, `type`, and `value`, and optionally `code`, `currency_code`, `include_tax`, `include_shipping`, `is_enabled`, and `is_default`. The module also accepts nested `rules` and `values` arrays, which the DTO doesn’t declare. A missing `code` is generated from `name`.
+
+- **Output**: the created rates, in input order
+- **Steps**: `createCommissionRatesStep`, compensated by deleting the created rates
+- **Hooks**: none
+
+## updateCommissionRatesWorkflow
+
+Updates fields on one or more rates. Workflow id `update-commission-rates`.
+
+| Input | Type |
+| --- | --- |
+| (root) | `UpdateCommissionRateDTO[]` |
+
+Each item needs an `id` and takes any `CreateCommissionRateDTO` field as optional.
+
+- **Output**: the updated rates
+- **Steps**: `updateCommissionRatesStep`
+- **Hooks**: none
+
+<Warning>
+  The compensation of `updateCommissionRatesStep` re-applies the step’s input, not the previous values. If a later step in a parent workflow fails, the rate keeps the new values.
+</Warning>
+
+## deleteCommissionRatesWorkflow
+
+Soft-deletes rates after checking that none of them is the global rate. Workflow id `delete-commission-rates`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `ids` | `string[]` | Ids of the rates to delete |
+
+- **Output**: none
+- **Steps**: `validateCommissionRatesDeletableStep`, which throws `NOT_ALLOWED` for an `is_default` rate, then `deleteCommissionRatesStep`, compensated by restoring the rates
+- **Hooks**: `commissionRatesDeleted`, with `{ ids }`
+
+## batchCommissionRulesWorkflow
+
+Creates, updates, and deletes the rules of one rate. Workflow id `batch-commission-rules`.
+
+| Input | Type | Description |
 | --- | --- | --- |
-| `createCommissionRatesWorkflow` | `CreateCommissionRateDTO[]` | Create rates (auto-generates `code`) |
-| `updateCommissionRatesWorkflow` | `UpdateCommissionRateDTO[]` | Update rate fields |
-| `deleteCommissionRatesWorkflow` | `{ ids[] }` | Delete rates (validates deletability first) |
+| `commission_rate_id` | `string` | The rate that new rules attach to |
+| `create` | `CreateCommissionRuleDTO[]`, optional | `{ reference, reference_id }` |
+| `update` | `UpdateCommissionRuleDTO[]`, optional | `{ id, reference?, reference_id? }` |
+| `delete` | `string[]`, optional | Ids of rules to delete |
+
+- **Output**: `{ created, updated, deleted }`, where `deleted` holds the ids
+- **Steps**: `createCommissionRulesStep`, `updateCommissionRulesStep`, and `deleteCommissionRulesStep`, run in parallel
+- **Hooks**: none
+
+Only `create` uses `commission_rate_id`. The ids in `update` and `delete` aren’t checked against it.
+
+## refreshOrderCommissionLinesWorkflow
 
-## Rule workflows
+Recomputes and replaces the commission lines of one or more orders. Workflow id `refresh-order-commission-lines`.
 
-| Workflow | Input | Purpose |
+| Input | Type | Description |
 | --- | --- | --- |
-| `batchCommissionRulesWorkflow` | `{ commission_rate_id, create?, update?, delete? }` | Create, update, and delete a rate's rules in one call |
+| `order_ids` | `string[]` | Orders to refresh. An unknown id throws |
 
-## Order-line workflows
+- **Output**: `CommissionLineDTO[]`, the lines written for all the orders
+- **Steps**: `fetch-orders` (`useQueryGraphStep`), `getCommissionLinesStep`, `upsertCommissionLinesStep`
+- **Called by**: `completeCartWithSplitOrdersWorkflow` and the `order-commission-refresh-handler` subscriber
 
-| Workflow | Input | Purpose |
+The workflow exposes two hooks:
+
+| Hook | Input | Return |
 | --- | --- | --- |
-| `refreshOrderCommissionLinesWorkflow` | `{ order_ids[] }` | Recompute and upsert an order's commission lines (idempotent) |
-
-<Note>
-  `deleteCommissionRatesWorkflow` exposes a `commissionRatesDeleted` hook, and
-  `batchCommissionRulesWorkflow` runs its create / update / delete steps in
-  parallel. `refreshOrderCommissionLinesWorkflow` also runs as a step inside the
-  cart-split checkout workflow.
-</Note>
-
-To work with records directly instead of through a workflow, see the
-[Service reference](/platform/commission/reference/service). To run side effects
-when an order changes, see the
-[Event reference](/platform/commission/reference/events).
+| `setCommissionContext` | `{ contexts: CommissionCalculationContext[] }` | `StepResponse` of new contexts, or nothing |
+| `commissionLinesUpserted` | `{ order_ids, commission_lines }` | Ignored |
+
+```ts
+refreshOrderCommissionLinesWorkflow.hooks.setCommissionContext(
+  ({ contexts }) =>
+    new StepResponse(
+      contexts.map((c) => ({ ...c, additional_context: { tier: "gold" } }))
+    )
+)
+```
+
+The handler above adds data to every context before the provider sees it. Neither `getCommissionLinesStep` nor `upsertCommissionLinesStep` defines a compensation.
+
+## Exported steps
+
+`@mercurjs/core/workflows` also exports each step, with its id, for use in your own workflows:
+
+| Step | Id |
+| --- | --- |
+| `createCommissionRatesStep` | `create-commission-rates-step` |
+| `updateCommissionRatesStep` | `update-commission-rates-step` |
+| `deleteCommissionRatesStep` | `delete-commission-rates-step` |
+| `validateCommissionRatesDeletableStep` | `validate-commission-rates-deletable-step` |
+| `createCommissionRulesStep` | `create-commission-rules-step` |
+| `updateCommissionRulesStep` | `update-commission-rules-step` |
+| `deleteCommissionRulesStep` | `delete-commission-rules-step` |
+| `getCommissionLinesStep` | `get-commission-lines` |
+| `upsertCommissionLinesStep` | `upsert-commission-lines` |