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

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

@@ -1,40 +1,134 @@
 ---
-title: "Workflows"
+title: "Catalog workflows"
 sidebarTitle: "Workflows"
-description: "Mercur's product create, review, and allowlist workflows."
+description: "Mercur's product create, review, allowlist, and category workflows: inputs, hooks, and events."
 ---
 
-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.
+Mercur ships 7 catalog workflows in `packages/core/src/workflows/product`. Import them from `@mercurjs/core/workflows` and run them with the Medusa container. For plain updates and deletes of products, variants, and categories, use Medusa's core flows, such as `updateProductsWorkflow`.
 
-## Product workflows
+```ts
+import { confirmProductsWorkflow } from "@mercurjs/core/workflows"
 
-| Workflow | Input | Purpose |
+await confirmProductsWorkflow(container).run({
+  input: { product_ids: ["prod_01JD8Q1234567"] },
+})
+```
+
+## createProductsWorkflow
+
+Creates master products with attributes and variants, links stores to them, and records each submission. Workflow id `mercur-create-products`. Returns the created `ProductDTO[]` in input order.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `products` | `(CreateProductDTO & { seller_ids?: string[] })[]` | Products to create. `CreateProductDTO` from `@mercurjs/types` replaces `options` with `attributes` |
+| `products[].seller_ids` | `string[]`, optional | Stores to put on the product's allowlist |
+| `created_by` | `string` | Submitter id, a seller id or a user id, stored on the audit record |
+| `additional_data` | `Record<string, unknown>`, optional | Forwarded to Medusa's product and variant workflows and the `productsCreated` hook |
+
+The workflow runs these steps in order:
+
+1. Runs the `validate` hook with `input` and `products`
+2. Creates the products with Medusa's `createProductsWorkflow`, each with an internal `__default__` option
+3. Attaches `attributes` with `addProductAttributesToProductWorkflow`
+4. Removes the `__default__` option from products that gained a variant axis
+5. Creates `variants` with `createProductVariantsWorkflow`, defaulting `manage_inventory` to `false`
+6. Links `seller_ids` with `associateSellersWithProductStep`
+7. Records a `PRODUCT_ADD` change per product with `recordProductAuditChangeWorkflow`
+8. Runs the `productsCreated` hook with `products` and `additional_data`
+9. Emits `product.created`
+
+It exposes the `validate` and `productsCreated` hooks. It emits `product.created` with `{ id }` for each product.
+
+## confirmProductsWorkflow
+
+Publishes `proposed` products. Workflow id `mercur-confirm-products`.
+
+| Input | Type | Description |
 | --- | --- | --- |
-| `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`) |
+| `product_ids` | `string[]` | Products to publish. All must be `proposed` |
+| `actor_id` | `string`, optional | Reviewer, stored as `created_by` and `confirmed_by` |
+| `internal_note` | `string`, optional | Operator note on each audit record |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the hook |
 
-## Allowlist & organization workflows
+Records a `STATUS_CHANGE` action with `{ status: "published" }` per product, then sets the status.
 
-| Workflow | Input | Purpose |
+It exposes the `productsConfirmed` hook with `product_ids`, `internal_note`, and `additional_data`. It emits `product.published` with `{ id, internal_note }` for each product.
+
+## rejectProductWorkflow
+
+Rejects one `proposed` product. Workflow id `mercur-reject-product`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `product_id` | `string` | Product to reject |
+| `message` | `string`, optional | Reason, stored as the change's `external_note` |
+| `actor_id` | `string`, optional | Reviewer |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the hook |
+
+Records a `STATUS_CHANGE` action with `{ status: "rejected" }`, then sets the status.
+
+It exposes the `productRejected` hook with `product_id`, `message`, and `additional_data`. It emits `product.rejected` with `{ id, message }`.
+
+## requestProductChangeWorkflow
+
+Asks the submitter to revise a `proposed` product without changing its status. Workflow id `mercur-request-product-change`.
+
+| Input | Type | Description |
 | --- | --- | --- |
-| `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).
+| `product_id` | `string` | Product to send back |
+| `message` | `string`, optional | Requested changes, stored as `external_note` |
+| `actor_id` | `string`, optional | Reviewer |
+| `additional_data` | `Record<string, unknown>`, optional | Passed to the hook |
+
+Records a `CHANGE_REQUESTED` action with `{ message }`.
+
+It exposes the `productChangeRequested` hook with `product_id`, `message`, and `additional_data`. It emits `product.change-requested` with `{ id, message, actor_id }`.
+
+## linkSellersToProductWorkflow
+
+Adds stores to and removes stores from a product's allowlist. Workflow id `mercur-link-sellers-to-product`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Product id |
+| `add` | `string[]`, optional | Seller ids to link |
+| `remove` | `string[]`, optional | Seller ids to unlink |
+
+Runs `associateSellersWithProductStep` and `detachSellersFromProductStep`, which undo their changes if the run fails. No hooks or events.
+
+## linkSellersToProductCategoryWorkflow
+
+Adds and removes `category_seller` rows for a category. Workflow id `mercur-link-sellers-to-product-category`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Category id |
+| `add` | `string[]`, optional | Seller ids to link |
+| `remove` | `string[]`, optional | Seller ids to unlink |
+
+Runs `associateSellersWithProductCategoryStep` and `detachSellersFromProductCategoryStep`. No hooks or events.
+
+## assignProductsToCategoryWorkflow
+
+Moves products into one category. Workflow id `mercur-assign-products-to-category`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Category id |
+| `add` | `string[]`, optional | Product ids. Each product's categories become `[id]` |
+| `remove` | `string[]`, optional | Product ids. Each product's categories become empty |
+
+Runs Medusa's `updateProductsWorkflow` with `category_ids`, so Medusa's product update events fire. No hooks of its own.
+
+## Exported steps
+
+These steps are exported for use in your own workflows:
+
+| Step | Does |
+| --- | --- |
+| `associateSellersWithProductStep` | Creates `product_seller` rows from `{ links: { product_id, seller_id }[] }` |
+| `detachSellersFromProductStep` | Dismisses `product_seller` rows with the same input |
+| `associateSellersWithProductCategoryStep` | Creates `category_seller` rows from `{ links: { category_id, seller_id }[] }` |
+| `detachSellersFromProductCategoryStep` | Dismisses `category_seller` rows with the same input |
+| `validateProductsStatusStep` | Throws `NOT_ALLOWED` unless every product in `products` has the `expected_status` |
+| `validateSellerProductPermissionsStep` | Throws `NOT_ALLOWED` when `seller_id` is linked to any of `category_ids` |

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

@@ -1,65 +1,67 @@
 ---
-title: "Order commission lines"
+title: "Commission lines on orders"
 sidebarTitle: "Order commission lines"
-description: "Per-order commission lines, how they're computed, and BigNumber precision."
+description: "What a commission line records, when Mercur writes and rewrites it, and how payouts read it."
 ---
 
-This page covers how commission is recorded on an order and kept in sync as the
-order changes.
+A commission line is the resolved commission for one line item or one shipping method of an order. It’s derived data: Mercur computes it from the current rates and the order’s contents, writes it at checkout, and rewrites it whenever the order changes. Payouts read these lines to work out what the seller receives.
 
-## Commission line
+## What a line records
 
-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`.
+A line is a `CommissionLine` record (id prefix `comline`). It points at exactly one of `item_id` or `shipping_method_id`, and it stores the rate it came from and the amount.
 
 ```ts
-// A commission line, as written by the refresh workflow
-{
-  item_id: "ordli_123",
+const line = {
+  id: "comline_01JD8Q1234567",
+  item_id: "ordli_01JD8Q1234567",
   shipping_method_id: null,
-  commission_rate_id: "comrate_123",
-  code: "standard-a1b2c3",
-  rate: 10,
-  amount: 250, // 10% of a 2500 subtotal
+  commission_rate_id: "comrate_01JD8Q1234567",
+  provider_id: "system",
+  code: "acme-apparel-k3x9qa",
+  rate: 12,
+  amount: 5.64,
   description: null,
+  data: 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>
+The fields carry these values from the `system` provider:
+
+- **`code`**: the code of the winning rate, kept so the line stays readable if the rate is renamed or deleted
+- **`rate`**: the percent for a percentage rate, or the fixed amount for a fixed rate
+- **`amount`**: the commission for the line, computed with `MathBN`
+- **`description`**: `Shipping Commission` on shipping lines, empty on item lines
+- **`provider_id`**: the provider that computed the line, `system` by default
+- **`data`**: free JSON a custom provider can fill
+
+## When lines are written
+
+Mercur writes lines at checkout and rewrites them when the order’s contents change. Both paths run `refreshOrderCommissionLinesWorkflow`:
+
+| Trigger | Where it runs |
+| --- | --- |
+| Cart completed | A nested step of `completeCartWithSplitOrdersWorkflow`, for every seller order in the group |
+| `order-edit.confirmed` | The `order-commission-refresh-handler` subscriber |
+| `order.return_received` | The same subscriber |
+| `order.claim_created` | The same subscriber |
+| `order.exchange_created` | The same subscriber |
+
+A refresh resolves against the rates that exist when it runs. Changing a rate doesn’t touch existing lines until the order is refreshed again.
+
+## A refresh replaces, it doesn’t append
+
+Computed lines carry no `id`. The module’s `upsertCommissionLines` first deletes every existing line whose `item_id` or `shipping_method_id` is in the new set, then inserts the new lines in the same transaction. Running a refresh twice leaves one line per item and shipping method.
+
+<Warning>
+  Deletion is keyed on the anchors in the new set. If an item no longer gets a line, for example because you disabled the only rate that matched it, its old line stays in place.
+</Warning>
+
+## How payouts use the lines
+
+`createPayoutWorkflow` reads every commission line whose `item_id` or `shipping_method_id` belongs to the order. It sums their `amount` and transfers the order `total` minus that sum to the seller’s payout account. With the lines from the [overview figure](/platform/commission/overview), an order total of € 92.00 and commission of € 10.14 pays the seller € 81.86.
+
+## Related
+
+- [Refresh an order’s lines from your own code](/platform/commission/guides/refresh-order-commission-lines)
+- [The order events that trigger a refresh](/platform/commission/reference/events)
+- [All `CommissionLine` fields](/platform/commission/reference/data-models)

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

@@ -1,86 +1,76 @@
 ---
-title: "Rule matching"
+title: "How Mercur picks a commission rate"
 sidebarTitle: "Rule matching"
-description: "The five dimensions, most-specific-wins resolution, tie-breaks, and shipping."
+description: "The five rule dimensions, AND and OR matching, most-specific-wins, the oldest-rate tie-break, and shipping."
 ---
 
-This page covers how Mercur decides which commission rate applies to a given
-order line.
+Rule matching decides which single rate commissions each order line. Mercur finds every enabled rate whose rules fit the line’s product and seller, then keeps the one scoped on the most dimensions. Knowing the algorithm lets you predict a seller’s commission before an order exists.
 
-## Commission rule
+<img className="block dark:hidden" src="/images/figures/commission-rule-matching-light.svg" alt="Resolving the rate for a Linen shirt sold by ACME in the Shirts category: four enabled rates match, the acme-shirts rate scopes on two dimensions and wins, lighting does not match, and the default rate ranks last." />
+<img className="hidden dark:block" src="/images/figures/commission-rule-matching-dark.svg" alt="Resolving the rate for a Linen shirt sold by ACME in the Shirts category: four enabled rates match, the acme-shirts rate scopes on two dimensions and wins, lighting does not match, and the default rate ranks last." />
 
-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.
+## Each dimension checks one product field
+
+A rule compares its `reference_id` with one field of the line’s product. The product comes from the order line, and the seller comes from the offer the customer bought.
+
+| `reference` | Matches when |
+| --- | --- |
+| `product` | `product.id` equals `reference_id` |
+| `product_type` | `product.type_id` equals `reference_id` |
+| `product_collection` | `product.collection_id` equals `reference_id` |
+| `product_category` | Any of `product.categories` has the id `reference_id` |
+| `seller` | The offer’s `seller_id` equals `reference_id` |
+
+Products are a shared catalog that no seller owns, which is why the `seller` dimension reads the offer on the line and not the product.
+
+<Warning>
+  The module stores `reference` as free text and doesn’t validate it. A rule with any other `reference`, such as a typo, never matches, so the whole rate never matches.
+</Warning>
+
+## AND across dimensions, OR within one
+
+Mercur groups a rate’s rules by `reference`. The rate matches a line when every group has at least one rule that matches. Rules in the same group are alternatives, and groups narrow each other.
 
 ```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" },
-    ],
-  },
-})
+const rules = [
+  { reference: "seller", reference_id: "sel_01JD8Q1234567" },
+  { reference: "product_category", reference_id: "pcat_01JD8Q1234567" },
+  { reference: "product_category", reference_id: "pcat_01JD8Q1234568" },
+]
 ```
 
-A rate with **no** rules is a catch-all that matches every line. A rate with
-rules only matches lines that satisfy them.
+A rate with these rules matches lines sold by that seller in either category. It doesn’t match the seller’s lines in other categories, or other sellers’ lines in those categories.
 
-## The five dimensions
+## The most specific rate wins
 
-A rule's `reference` is one of five dimensions, each resolved against the order
-line's product:
+When several rates match, Mercur sorts them by specificity and keeps the first. Specificity is the number of distinct dimensions a rate’s rules use, not the number of rules. The rules above give a specificity of 2.
 
-| `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` |
+Mercur resolves each line in this order:
 
-<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>
+1. Drop disabled rates and rates whose `currency_code` is set to another currency.
+2. Keep the rates that match the line. A rate without rules always matches.
+3. Sort by specificity, highest first.
+4. Break ties by `created_at`, oldest first.
+5. Apply the first rate to the line’s base amount.
 
-## Most-specific-wins
+The global rate has no rules, so its specificity is 0 and any matching scoped rate beats it. If no enabled rate matches, the line gets no commission line.
 
-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.
+<Warning>
+  The tie-break also applies between rule-less rates. If you create a second rate without rules, it competes with the global rate at specificity 0, and the older of the two wins.
+</Warning>
 
-```
-Rate A: seller = sel_123                          (specificity 1)
-Rate B: seller = sel_123 AND category = pcat_shoes (specificity 2)  ← wins
-```
+## Shipping uses the global rate only
 
-<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>
+Shipping methods aren’t matched against rules. If the global rate has `include_shipping` set, every shipping method on the order gets a line from it, with the description `Shipping Commission`. Otherwise shipping isn’t commissioned.
 
-## Tie-break
+The global rate’s `include_tax` flag applies to shipping too, adding the method’s `tax_total` to its `subtotal`. For a fixed global rate, each shipping method gets the fixed amount.
 
-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.
+## Rates load once per batch
 
-## Shipping commission
+The `system` provider loads all enabled rates with their rules and values in one query per batch of orders. It then resolves every line of every order in memory. Adding rates doesn’t add queries per line.
 
-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.
+## Related
 
-<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>
+- [Rate types, per-currency values, and the global commission](/platform/commission/concepts/rules-and-rates)
+- [Scope a rate with batchCommissionRulesWorkflow](/platform/commission/guides/batch-update-rules)
+- [Write your own provider to replace this algorithm](/platform/commission/reference/service)

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

@@ -1,84 +1,86 @@
 ---
-title: "Rules & rates"
+title: "Commission rates and rules"
 sidebarTitle: "Rules & rates"
-description: "The commission rate, its fixed and percentage forms, and per-currency amounts."
+description: "How a commission rate expresses the marketplace's cut, how rules scope it, and what the global commission does."
 ---
 
-This page covers how a commission rate is modeled and the two ways it can
-express the marketplace's cut.
+A commission rate is the cut the marketplace takes from a sale, and rules decide which lines it applies to. Every marketplace has one global rate that covers everything, and you add scoped rates on top of it for specific sellers or parts of the catalog. Getting this model right decides what every seller is paid.
 
-## Commission rate
+## A rate is a type and a value
 
-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.
+A rate is a `CommissionRate` record (id prefix `comrate`). Its `type` says how to read its `value`, and two flags change the base amount the value applies to.
 
-```ts
-const { result } = await createCommissionRatesWorkflow(container).run({
-  input: [
-    {
-      name: "Standard",
-      type: CommissionRateType.PERCENTAGE,
-      value: 10,
-    },
-  ],
-})
-```
+| `type` | How `value` is read | Line `amount` |
+| --- | --- | --- |
+| `percentage` | A percent, so `10` means 10% | `base × value ÷ 100` |
+| `fixed` | A flat amount per line item | The per-currency amount, or `value` |
 
-A rate is either **percentage** or **fixed**, set by `type`
-(`CommissionRateType`):
+The base amount is the line’s `subtotal`. A rate changes it with these flags:
 
-| 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 |
+- **`include_tax`**: adds the line’s `tax_total` to the base before the rate applies
+- **`include_shipping`**: lets the rate commission shipping methods, and only takes effect on the global rate
+- **`is_enabled`**: disabled rates are skipped during resolution
 
-<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
+<Warning>
+  A fixed rate applies once per line item, not once per unit. A line with a quantity of 3 still gets one fixed amount. The `system` provider doesn’t cap a fixed amount at the line total.
+</Warning>
 
-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.
+Each rate also has a `name` and a unique `code`. When you create a rate without a `code`, the module builds one from the name plus a random suffix, so `"Standard"` becomes something like `standard-k3x9qa`.
 
 ```ts
+import { CommissionRateType } from "@mercurjs/types"
+import { createCommissionRatesWorkflow } from "@mercurjs/core/workflows"
+
 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 },
-      ],
-    },
+    { name: "Standard", type: CommissionRateType.PERCENTAGE, value: 10 },
   ],
 })
 ```
 
-<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 example creates a 10% rate with no rules, which matches every line until a more specific rate wins.
+
+## Per-currency amounts for fixed rates
+
+A fixed rate holds one amount per currency in `CommissionRateValue` records (id prefix `comval`). During resolution, Mercur picks the value whose `currency_code` equals the order’s currency. When none matches, it uses the rate’s own `value`.
+
+Percentage rates ignore `values`, because a percent is the same in every currency. A rate’s own `currency_code` field is separate: when it’s set, the rate only applies to orders in that currency.
+
+| Rate | `values` | Order in `usd` | Order in `gbp` |
+| --- | --- | --- | --- |
+| fixed, `value: 3` | `usd: 2.5`, `eur: 2` | 2.5 per line | 3 per line |
+| percentage, `value: 10` | ignored | 10% of base | 10% of base |
+
+## Rules scope a rate
+
+A rule is a `CommissionRule` record (id prefix `comrule`) that belongs to one rate. It’s a `reference` naming a dimension and a `reference_id` naming the record, for example `seller` and `sel_01JD8Q1234567`. A rate without rules matches every line. A rate with rules matches only the lines that satisfy them.
+
+The five dimensions are:
+
+- **`product`**: a master product id
+- **`product_type`**: a product type id
+- **`product_collection`**: a collection id
+- **`product_category`**: a category id
+- **`seller`**: the seller of the offer on the order line
+
+[Rule matching](/platform/commission/concepts/rule-matching) explains how rules combine and which rate wins when several match.
 
 ## 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.
+The global commission is the rate with `is_default: true`. The module seeds it on boot when none exists, as a 0% percentage rate named `Default` with the code `default`. You raise it to set the marketplace’s baseline cut.
+
+The global rate has rules that set it apart:
+
+- **Always present**: `deleteCommissionRatesWorkflow` throws `NOT_ALLOWED` if you try to delete it
+- **Fallback for items**: it has no rules, so it matches every line and loses to any scoped rate that also matches
+- **Only shipping rate**: its `include_shipping` flag is the only one that produces shipping commission lines
 
 <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.
+  Nothing stops you from setting `include_shipping` on a scoped rate, but the flag has no effect there. Shipping is resolved from the global rate alone.
 </Note>
+
+## Related
+
+- [How Mercur picks one rate for each line](/platform/commission/concepts/rule-matching)
+- [Create a rate from your server code](/platform/commission/guides/create-a-rate)
+- [All `CommissionRate` fields](/platform/commission/reference/data-models)