@mercurjs/docs 2.2.1 → 2.3.0-canary.1

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

@@ -0,0 +1,40 @@
+---
+title: "Workflows"
+sidebarTitle: "Workflows"
+description: "Mercur's product create, review, and allowlist workflows."
+---
+
+This reference lists the Mercur workflows for the Catalog domain. Import them
+from `@mercurjs/core/workflows` and run them against the Medusa container. They
+wrap Medusa's native product flows to add the marketplace layer: the store
+allowlist, the review lifecycle, and the audit trail.
+
+## Product workflows
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `createProductsWorkflow` | `{ products[], created_by, additional_data? }` | Create master products, attach attributes/variants, record the submission, allowlist `seller_ids` |
+| `confirmProductsWorkflow` | `{ product_ids[], actor_id?, internal_note? }` | `proposed` → `published` |
+| `rejectProductWorkflow` | `{ product_id, message?, actor_id? }` | `proposed` → `rejected` |
+| `requestProductChangeWorkflow` | `{ product_id, message?, actor_id? }` | Ask the submitter for a revision (stays `proposed`) |
+
+## Allowlist & organization workflows
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `linkSellersToProductWorkflow` | `{ id, add?, remove? }` | Add/remove stores on a product's allowlist |
+| `linkSellersToProductCategoryWorkflow` | `{ id, add?, remove? }` | Add/remove stores on a category's allowlist |
+| `assignProductsToCategoryWorkflow` | `{ id, add?, remove? }` | Assign products to a single category |
+
+<Note>
+  For plain create/update/delete of products, variants, and categories, Mercur
+  reuses Medusa's native core-flows (`createProductsWorkflow`,
+  `updateProductsWorkflow`, `createProductVariantsWorkflow`, and so on) under the
+  hood. The workflows above are the Mercur-specific entry points that add the
+  allowlist, review lifecycle, and audit history.
+</Note>
+
+To work with records directly instead of through a workflow, see the
+[Service reference](/platform/catalog/reference/service). To run side effects
+when a product changes, see the
+[Event reference](/platform/catalog/reference/events).

package/content/platform/commission/concepts/order-commission-lines.mdx

@@ -0,0 +1,65 @@
+---
+title: "Order commission lines"
+sidebarTitle: "Order commission lines"
+description: "Per-order commission lines, how they're computed, and BigNumber precision."
+---
+
+This page covers how commission is recorded on an order and kept in sync as the
+order changes.
+
+## Commission line
+
+A commission line is the resolved commission for a single order line. It's
+represented by the `CommissionLine` data model (table `commission_line`, id
+prefix `comline`). Each line anchors to either an item (`item_id`) or a shipping
+method (`shipping_method_id`). It records the rate that matched
+(`commission_rate_id`, `code`), the applied `rate`, and the computed `amount`.
+
+```ts
+// A commission line, as written by the refresh workflow
+{
+  item_id: "ordli_123",
+  shipping_method_id: null,
+  commission_rate_id: "comrate_123",
+  code: "standard-a1b2c3",
+  rate: 10,
+  amount: 250, // 10% of a 2500 subtotal
+  description: null,
+}
+```
+
+Lines are generated automatically during checkout. When the cart is split into
+per-seller orders, `refreshOrderCommissionLinesWorkflow` runs against each new
+order. Shipping lines carry a `"Shipping Commission"` description. Item lines
+carry none.
+
+## Recomputed on change
+
+Commission lines are **derived** data, not a one-time snapshot. The lines are
+recomputed whenever an order's composition changes, such as when an order edit
+is confirmed, a return is received, or a claim or exchange is created. That
+keeps the seller's commission tracking what the customer actually kept.
+
+The refresh is **idempotent**: it deletes any existing lines for the affected
+items and shipping methods, then inserts the freshly computed set. Re-running it
+never duplicates lines.
+
+<Note>
+  Computed lines carry no `id`. The module's `upsertCommissionLines` deletes by
+  anchor (`item_id` / `shipping_method_id`) before inserting, which is what
+  makes repeated refreshes safe.
+</Note>
+
+## BigNumber precision
+
+All commission arithmetic uses Medusa's `MathBN` (BigNumber). It's arbitrary
+precision, so percentages and per-currency amounts never accumulate
+floating-point error. A percentage amount is `subtotal × value ÷ 100`. A fixed
+amount is the per-currency value (or the fallback `value`). Each is computed in
+BigNumber before being stored.
+
+<Tip>
+  Commission lines feed the payout pipeline: when a seller's payout is
+  calculated, the order's commission lines are read straight from the commission
+  module and deducted from the amount transferred to the seller.
+</Tip>

package/content/platform/commission/concepts/rule-matching.mdx

@@ -0,0 +1,86 @@
+---
+title: "Rule matching"
+sidebarTitle: "Rule matching"
+description: "The five dimensions, most-specific-wins resolution, tie-breaks, and shipping."
+---
+
+This page covers how Mercur decides which commission rate applies to a given
+order line.
+
+## Commission rule
+
+A commission rule scopes a rate to part of the catalog. It's represented by the
+`CommissionRule` data model (table `commission_rule`, id prefix `comrule`). A
+rule is a `reference` / `reference_id` pair that belongs to one rate. The
+`reference` names the dimension, and the `reference_id` names the specific
+record.
+
+```ts
+await batchCommissionRulesWorkflow(container).run({
+  input: {
+    commission_rate_id: "comrate_123",
+    create: [
+      { reference: "seller", reference_id: "sel_123" },
+      { reference: "product_category", reference_id: "pcat_shoes" },
+    ],
+  },
+})
+```
+
+A rate with **no** rules is a catch-all that matches every line. A rate with
+rules only matches lines that satisfy them.
+
+## The five dimensions
+
+A rule's `reference` is one of five dimensions, each resolved against the order
+line's product:
+
+| `reference` | Matches when |
+| --- | --- |
+| `product` | The line's product id equals `reference_id` |
+| `product_type` | The product's type id equals `reference_id` |
+| `product_collection` | The product's collection id equals `reference_id` |
+| `product_category` | One of the product's categories equals `reference_id` |
+| `seller` | The seller behind the line's offer equals `reference_id` |
+
+<Note>
+  Products are the shared master catalog. The `seller` dimension resolves
+  through the **offer** on the order line (`item.offer.seller_id`), not through
+  product ownership.
+</Note>
+
+## Most-specific-wins
+
+When several rates match a line, resolution is **AND across dimensions, OR
+within a dimension**. Rules are grouped by `reference`. A rate matches only when
+**every** group it defines has at least one matching rule. Among the matching
+rates, the one scoped on the **most distinct dimensions** wins.
+
+```
+Rate A: seller = sel_123                          (specificity 1)
+Rate B: seller = sel_123 AND category = pcat_shoes (specificity 2)  ← wins
+```
+
+<Tip>
+  Specificity is the count of **distinct dimensions** a rate scopes on, not the
+  number of rules. Two `product_category` rules on one rate still count as a
+  single dimension (they OR together).
+</Tip>
+
+## Tie-break
+
+When two matching rates have equal specificity, the **oldest** rate wins. Rates
+are evaluated `created_at` ascending, so the earliest-created rate is the
+deterministic winner.
+
+## Shipping commission
+
+Item commission is resolved per line as above. Shipping is different: a
+shipping method is commissioned **only** by the global rate, and only when its
+`include_shipping` flag is on. No scoped rate can commission shipping.
+
+<Note>
+  `include_tax` is a separate, per-rate toggle. When on, the line's `tax_total`
+  is added to the base amount before the rate is applied. This holds for both
+  item and shipping commission.
+</Note>

package/content/platform/commission/concepts/rules-and-rates.mdx

@@ -0,0 +1,84 @@
+---
+title: "Rules & rates"
+sidebarTitle: "Rules & rates"
+description: "The commission rate, its fixed and percentage forms, and per-currency amounts."
+---
+
+This page covers how a commission rate is modeled and the two ways it can
+express the marketplace's cut.
+
+## Commission rate
+
+A commission rate is the number the marketplace takes from a sale. It's
+represented by the `CommissionRate` data model (table `commission_rate`, id
+prefix `comrate`). A rate has a `name`, a unique `code`, a `type`, and a
+`value`, plus the `include_tax` and `include_shipping` toggles.
+
+```ts
+const { result } = await createCommissionRatesWorkflow(container).run({
+  input: [
+    {
+      name: "Standard",
+      type: CommissionRateType.PERCENTAGE,
+      value: 10,
+    },
+  ],
+})
+```
+
+A rate is either **percentage** or **fixed**, set by `type`
+(`CommissionRateType`):
+
+| Type | How `value` is read |
+| --- | --- |
+| `percentage` | A percent of the line's base amount (e.g. `10` → 10%) |
+| `fixed` | A flat amount deducted per line |
+
+<Note>
+  A rate's `code` is unique. When you create a rate without one, the module
+  auto-generates a URL-safe code from the `name` (e.g. `"Standard"` →
+  `standard-a1b2c3`).
+</Note>
+
+## Per-currency amounts
+
+A fixed rate can carry a different amount for each currency. This is
+represented by the `CommissionRateValue` data model (table
+`commission_rate_value`, id prefix `comval`). Each value pairs a `currency_code`
+with an `amount`, and the calculation picks the value matching the order's
+currency.
+
+```ts
+await createCommissionRatesWorkflow(container).run({
+  input: [
+    {
+      name: "Flat fee",
+      type: CommissionRateType.FIXED,
+      value: 5, // fallback when no per-currency value matches
+      values: [
+        { currency_code: "usd", amount: 5 },
+        { currency_code: "eur", amount: 4 },
+      ],
+    },
+  ],
+})
+```
+
+<Tip>
+  When no `values` entry matches the order's currency, a fixed rate falls back
+  to its scalar `value`. Percentage rates ignore `values` entirely. A percent
+  is currency-independent.
+</Tip>
+
+## The global commission
+
+Every marketplace has exactly one **Global Commission**. This is the rate with
+`is_default` set to `true`. Mercur seeds it at boot (a `0%` percentage rate
+named `Default`) so a rate always exists, and it applies whenever no
+more-specific rate matches a line.
+
+<Note>
+  The global rate is also the **only** rate that can commission shipping. See
+  [Rule matching](/platform/commission/concepts/rule-matching) for how
+  specificity and shipping are resolved.
+</Note>

package/content/platform/commission/guides/batch-update-rules.mdx

@@ -0,0 +1,58 @@
+---
+title: "Batch-update commission rules"
+sidebarTitle: "Batch-update rules"
+description: "Create, update, and delete a rate's rules in a single call."
+---
+
+In this guide, you'll learn how to manage the rules that scope a commission rate
+from your own server code, adding, changing, and removing them in one atomic
+operation.
+
+## Run the workflow
+
+`batchCommissionRulesWorkflow` applies creates, updates, and deletes to a single
+rate's rules in parallel. Pass the target `commission_rate_id` and any of the
+`create`, `update`, and `delete` arrays.
+
+```ts title="src/api/custom/rules/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { batchCommissionRulesWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const { result } = await batchCommissionRulesWorkflow(req.scope).run({
+    input: {
+      commission_rate_id: "comrate_123",
+      create: [
+        { reference: "seller", reference_id: "sel_123" },
+        { reference: "product_category", reference_id: "pcat_shoes" },
+      ],
+      update: [{ id: "comrule_456", reference_id: "pcat_boots" }],
+      delete: ["comrule_789"],
+    },
+  })
+
+  res.json(result)
+}
+```
+
+The result groups the affected rules as `{ created, updated, deleted }`.
+
+<Note>
+  Every rule's `reference` must be one of the five dimensions: `product`,
+  `product_type`, `product_collection`, `product_category`, or `seller`. The
+  `reference_id` is the id of the specific record in that dimension.
+</Note>
+
+## How scoping changes matching
+
+Adding rules **narrows** a rate. Rules on the same dimension OR together. Rules
+across dimensions AND together. The two `create` rules above make the rate match
+only lines that are both from seller `sel_123` **and** in category `pcat_shoes`,
+raising the rate's specificity to `2`.
+
+<Tip>
+  Increasing a rate's specificity makes it win over less-specific rates on the
+  lines it matches. See
+  [Rule matching](/platform/commission/concepts/rule-matching) for how
+  most-specific-wins and tie-breaks resolve.
+</Tip>

package/content/platform/commission/guides/create-a-rate.mdx

@@ -0,0 +1,72 @@
+---
+title: "Create a commission rate"
+sidebarTitle: "Create a rate"
+description: "Create a commission rate programmatically with createCommissionRatesWorkflow."
+---
+
+In this guide, you'll learn how to create a commission rate from your own server
+code. This is useful in a seed script, a custom API route, or an onboarding flow.
+
+Mercur exposes a `createCommissionRatesWorkflow` that creates one or more
+`CommissionRate` records. Run it from any place that has access to the Medusa
+container.
+
+## Run the workflow
+
+```ts title="src/api/custom/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { createCommissionRatesWorkflow } from "@mercurjs/core/workflows"
+import { CommissionRateType } from "@mercurjs/types"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const { result } = await createCommissionRatesWorkflow(req.scope).run({
+    input: [
+      {
+        name: "Standard",
+        type: CommissionRateType.PERCENTAGE,
+        value: 10,
+      },
+    ],
+  })
+
+  res.status(201).json({ commission_rate: result[0] })
+}
+```
+
+<Note>
+  The workflow takes an **array** of rates and returns the created records. When
+  you omit `code`, the module generates a unique one from `name`.
+</Note>
+
+## Create a fixed, per-currency rate
+
+For a flat fee, use `CommissionRateType.FIXED` and pass per-currency `values`.
+The scalar `value` is the fallback when no currency matches.
+
+```ts
+await createCommissionRatesWorkflow(req.scope).run({
+  input: [
+    {
+      name: "Flat fee",
+      type: CommissionRateType.FIXED,
+      value: 5,
+      values: [
+        { currency_code: "usd", amount: 5 },
+        { currency_code: "eur", amount: 4 },
+      ],
+    },
+  ],
+})
+```
+
+## Scope the rate
+
+A rate created without rules is a catch-all. To scope it to part of the catalog,
+attach rules with
+[`batchCommissionRulesWorkflow`](/platform/commission/guides/batch-update-rules).
+
+<Tip>
+  Only the global rate (`is_default`) may commission shipping. To let the global
+  rate take a cut of shipping, update it with `include_shipping: true` via
+  `updateCommissionRatesWorkflow`.
+</Tip>

package/content/platform/commission/guides/refresh-order-commission-lines.mdx

@@ -0,0 +1,55 @@
+---
+title: "Refresh order commission lines"
+sidebarTitle: "Refresh order lines"
+description: "Recompute an order's commission lines after it changes."
+---
+
+In this guide, you'll learn how to recompute the commission lines for an order
+from your own server code. Mercur already refreshes lines automatically at
+checkout and on order changes. Reach for this workflow when you change an order
+outside those paths, or when backfilling.
+
+## Run the workflow
+
+`refreshOrderCommissionLinesWorkflow` reads each order, resolves the matching
+rate for every item and shipping method, and writes the resulting
+`CommissionLine` records.
+
+```ts title="src/api/custom/refresh/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { refreshOrderCommissionLinesWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const { result } = await refreshOrderCommissionLinesWorkflow(req.scope).run({
+    input: { order_ids: [req.params.id] },
+  })
+
+  res.json({ commission_lines: result })
+}
+```
+
+<Note>
+  The workflow takes an array of `order_ids`, so you can refresh many orders in
+  one run. This is useful for backfilling after you change your commission
+  configuration.
+</Note>
+
+## Idempotency
+
+The refresh is a **delete-then-insert** for each affected item and shipping
+method, so re-running it never duplicates lines. You can call it as often as you
+need without cleaning up first.
+
+## When it runs automatically
+
+You rarely need to call this by hand. Mercur runs it for you:
+
+- **At checkout:** as each per-seller order is created from the split cart.
+- **On order changes:** a subscriber re-runs it when an order edit is
+  confirmed, or a return, claim, or exchange is created.
+
+<Tip>
+  To hook your own logic into these moments, subscribe to the same order events
+  rather than re-running this workflow. See the
+  [Events reference](/platform/commission/reference/events).
+</Tip>

package/content/platform/commission/overview.mdx

@@ -0,0 +1,86 @@
+---
+title: "Commission"
+sidebarTitle: "Overview"
+description: "Configure how the marketplace takes its cut of every seller order."
+---
+
+Use Mercur to keep financial control over what share of each sale the
+marketplace keeps and each seller earns.
+
+Financial control over the marketplace runs through commission. You set
+policy-based **rates** (fixed or percentage) and scope them to parts of your
+catalog with **rules**. Mercur resolves the right rate for every order line by
+most-specific-wins and writes an auditable **commission line**. That line is the
+exact amount deducted before the seller is paid out, computed in arbitrary
+precision so the numbers reconcile.
+
+<Note>
+  **Commission = the `CommissionRate` + `CommissionRule` entities.** A rate is
+  the number, either a percentage or a fixed amount. Rules scope that rate to a
+  slice of the catalog. Every marketplace has one **Global Commission**. This is
+  the `is_default` rate that applies when nothing more specific matches.
+</Note>
+
+## Key features
+
+- **Fixed or percentage:** a percentage of the line, or a flat per-currency amount.
+- **Per-currency amounts:** fixed rates carry an amount per currency, falling back to a default `value`.
+- **Five scoping dimensions:** match on `product`, `product_type`, `product_collection`, `product_category`, and `seller`.
+- **Most-specific-wins:** the rate scoped on the most dimensions wins, and ties break to the oldest rate.
+- **Shipping commission:** only the global rate may commission shipping (`include_shipping`).
+- **Automatic order lines:** a commission line is generated per item and recomputed when an order changes.
+- **BigNumber arithmetic:** all commission math uses arbitrary precision for financial accuracy.
+
+## Get started
+
+Learn how the domain fits together.
+
+<CardGroup cols={2}>
+  <Card title="Rules & rates" icon="percent" href="/platform/commission/concepts/rules-and-rates">
+    Fixed vs. percentage rates, per-currency amounts, and the global rate.
+  </Card>
+  <Card title="Rule matching" icon="sliders" href="/platform/commission/concepts/rule-matching">
+    The five dimensions, most-specific-wins, tie-breaks, and shipping.
+  </Card>
+  <Card title="Order commission lines" icon="receipt" href="/platform/commission/concepts/order-commission-lines">
+    How per-order lines are computed and kept in sync.
+  </Card>
+</CardGroup>
+
+## Examples
+
+Build against the Commission domain in your own code.
+
+<CardGroup cols={2}>
+  <Card title="Create a rate" icon="plus" href="/platform/commission/guides/create-a-rate">
+    Run `createCommissionRatesWorkflow` from a route or seed script.
+  </Card>
+  <Card title="Batch-update rules" icon="list-check" href="/platform/commission/guides/batch-update-rules">
+    Create, update, and delete a rate's rules in one call.
+  </Card>
+  <Card title="Refresh order lines" icon="arrows-rotate" href="/platform/commission/guides/refresh-order-commission-lines">
+    Recompute commission for an order after it changes.
+  </Card>
+</CardGroup>
+
+## Resources
+
+Data models, workflows, service methods, and events for the Commission domain.
+
+<CardGroup cols={2}>
+  <Card title="Data models" icon="table" href="/platform/commission/reference/data-models">
+    `CommissionRate`, `CommissionRule`, and related entities.
+  </Card>
+  <Card title="Links" icon="link" href="/platform/commission/reference/links">
+    How Commission connects to catalog, sellers, and orders.
+  </Card>
+  <Card title="Workflows" icon="diagram-project" href="/platform/commission/reference/workflows">
+    Rate, rule, and order-line workflows.
+  </Card>
+  <Card title="Service" icon="gear" href="/platform/commission/reference/service">
+    Module service methods for working with records directly.
+  </Card>
+  <Card title="Events" icon="bell" href="/platform/commission/reference/events">
+    How commission stays in sync with order changes.
+  </Card>
+</CardGroup>

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

@@ -0,0 +1,75 @@
+---
+title: "Data models"
+sidebarTitle: "Data models"
+description: "The data models owned by the Commission domain."
+---
+
+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).
+
+## CommissionRate
+
+Table `commission_rate`, id prefix `comrate`. The rate the marketplace takes
+from a sale.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `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`).
+
+## CommissionRule
+
+Table `commission_rule`, id prefix `comrule`. Scopes a rate to a slice of the
+catalog.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `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`) |
+
+## CommissionRateValue
+
+Table `commission_rate_value`, id prefix `comval`. A per-currency amount for a
+fixed rate.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `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`) |
+
+## CommissionLine
+
+Table `commission_line`, id prefix `comline`. The resolved commission for one
+order line.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `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>

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

@@ -0,0 +1,58 @@
+---
+title: "Event reference"
+sidebarTitle: "Events"
+description: "How the Commission domain stays in sync with order changes."
+---
+
+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.
+
+## Events it reacts to
+
+Mercur ships a subscriber (`order-commission-refresh-handler`) that re-runs
+`refreshOrderCommissionLinesWorkflow` for the affected 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 |
+
+Because the refresh is idempotent (delete-then-insert), reacting to several
+events for the same order never duplicates lines.
+
+## Run your own side effects
+
+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.
+
+```ts title="src/subscribers/commission-changed.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { OrderWorkflowEvents } from "@medusajs/framework/utils"
+
+export default async function commissionChangedHandler({
+  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.
+}
+
+export const config: SubscriberConfig = {
+  event: OrderWorkflowEvents.RETURN_RECEIVED,
+}
+```
+
+<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.
+</Note>