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

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

@@ -1,58 +1,86 @@
 ---
 title: "Batch-update commission rules"
 sidebarTitle: "Batch-update rules"
-description: "Create, update, and delete a rate's rules in a single call."
+description: "Add, change, and remove a commission rate's rules in one workflow run with batchCommissionRulesWorkflow."
 ---
 
-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.
+Change the rules that scope a commission rate in one run, for example to move a seller onto a negotiated rate or to retarget a rate at a new category.
 
-## Run the workflow
+## Before you begin
 
-`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.
+You need the following:
 
-```ts title="src/api/custom/rules/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { batchCommissionRulesWorkflow } from "@mercurjs/core/workflows"
+- The id of the rate to change, such as `comrate_01JD8Q1234567`
+- The ids of the rules to update or delete, from the rate’s `rules` relation
 
-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"],
-    },
-  })
+<Steps>
+  <Step title="Look up the rate's rules">
+    List the rate’s current rules through the module service.
 
-  res.json(result)
-}
-```
+    ```ts
+    import { MercurModules } from "@mercurjs/types"
 
-The result groups the affected rules as `{ created, updated, deleted }`.
+    const commission = container.resolve(MercurModules.COMMISSION)
+
+    const rules = await commission.listCommissionRules({
+      commission_rate_id: "comrate_01JD8Q1234567",
+    })
+    ```
+
+    Each rule has an `id`, a `reference`, and a `reference_id`. You need the `id` to update or delete a rule.
+
+  </Step>
+  <Step title="Run the batch">
+    Call `batchCommissionRulesWorkflow` from an API route. This route adds a seller rule, retargets a category rule, and removes a product rule.
+
+    ```ts title="src/api/admin/commission-scopes/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_01JD8Q1234567",
+          create: [{ reference: "seller", reference_id: "sel_01JD8Q1234567" }],
+          update: [
+            { id: "comrule_01JD8Q1234567", reference_id: "pcat_01JD8Q1234568" },
+          ],
+          delete: ["comrule_01JD8Q1234569"],
+        },
+      })
+
+      res.json(result)
+    }
+    ```
+
+    The result is `{ created, updated, deleted }`: the created and updated rules, and the deleted ids.
+
+  </Step>
+</Steps>
+
+## How the three operations run
+
+The workflow runs `createCommissionRulesStep`, `updateCommissionRulesStep`, and `deleteCommissionRulesStep` in parallel. Each array is optional, and an empty or missing one is a no-op. If any step fails, the others roll back: created rules are deleted, updated rules get their old values, and deleted rules are created again.
 
 <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.
+  A rolled-back delete creates new rule records with the same `reference` and `reference_id`. The rules keep their meaning, but their ids change.
 </Note>
 
-## How scoping changes matching
+## How the new rules change matching
+
+Adding rules narrows a rate. Rules on the same dimension are alternatives, and rules on different dimensions must all match. Adding the `seller` rule above to a rate that already had a `product_category` rule raises its specificity from 1 to 2, so it now beats single-dimension rates on that seller’s lines in that category.
+
+Use only the five supported references: `product`, `product_type`, `product_collection`, `product_category`, and `seller`. The module stores any string, and a rule with an unknown reference makes the rate match nothing.
+
+## Recompute existing orders
+
+Rule changes affect orders placed or refreshed after the change. To apply new rules to existing orders, run `refreshOrderCommissionLinesWorkflow` for them.
 
-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`.
+## Next steps
 
-<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>
+- [Refresh order commission lines after a rule change](/platform/commission/guides/refresh-order-commission-lines)
+- [See how specificity and tie-breaks pick a rate](/platform/commission/concepts/rule-matching)
+- [Input and output of batchCommissionRulesWorkflow](/platform/commission/reference/workflows)

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

@@ -1,72 +1,120 @@
 ---
 title: "Create a commission rate"
 sidebarTitle: "Create a rate"
-description: "Create a commission rate programmatically with createCommissionRatesWorkflow."
+description: "Create percentage and fixed commission rates from a seed script or API route 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.
+Create commission rates from your own server code, for example to seed a new marketplace or to set a seller’s rate during onboarding.
 
-Mercur exposes a `createCommissionRatesWorkflow` that creates one or more
-`CommissionRate` records. Run it from any place that has access to the Medusa
-container.
+## Before you begin
 
-## Run the workflow
+You need the following:
 
-```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"
+- A Mercur project with `@mercurjs/core` registered through `withMercur()`
+- The id of any seller, product, or category you want to scope a rate to
 
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
-  const { result } = await createCommissionRatesWorkflow(req.scope).run({
-    input: [
-      {
-        name: "Standard",
-        type: CommissionRateType.PERCENTAGE,
-        value: 10,
+<Steps>
+  <Step title="Create a percentage rate">
+    Run `createCommissionRatesWorkflow` with an array of rates. This seed script creates a 12% rate for apparel.
+
+    ```ts title="src/scripts/seed-commission.ts"
+    import type { ExecArgs } from "@medusajs/framework/types"
+    import { CommissionRateType } from "@mercurjs/types"
+    import { createCommissionRatesWorkflow } from "@mercurjs/core/workflows"
+
+    export default async function seedCommission({ container }: ExecArgs) {
+      const { result } = await createCommissionRatesWorkflow(container).run({
+        input: [
+          {
+            name: "Apparel",
+            code: "apparel",
+            type: CommissionRateType.PERCENTAGE,
+            value: 12,
+          },
+        ],
+      })
+
+      console.log(result.map((rate) => rate.id))
+    }
+    ```
+
+    The workflow returns the created rates in input order. If you leave out `code`, the module generates one from `name` with a random suffix, so set it when other code needs to find the rate by code.
+
+  </Step>
+  <Step title="Run the script">
+    Run the script with the Medusa CLI from your API app.
+
+    ```bash
+    npx medusa exec ./src/scripts/seed-commission.ts
+    ```
+
+    A rate without rules matches every line, so it competes with the global rate until you scope it.
+
+  </Step>
+  <Step title="Scope the rate">
+    Attach rules with `batchCommissionRulesWorkflow`, passing the id of the rate you created.
+
+    ```ts title="src/scripts/seed-commission.ts"
+    import { batchCommissionRulesWorkflow } from "@mercurjs/core/workflows"
+
+    await batchCommissionRulesWorkflow(container).run({
+      input: {
+        commission_rate_id: result[0].id,
+        create: [
+          { reference: "product_type", reference_id: "ptyp_01JD8Q1234567" },
+        ],
       },
-    ],
-  })
+    })
+    ```
+
+    The rate now matches only lines whose product has that type. See [Batch-update commission rules](/platform/commission/guides/batch-update-rules) for updates and deletes.
+
+  </Step>
+</Steps>
 
-  res.status(201).json({ commission_rate: result[0] })
+## Create a fixed rate with per-currency amounts
+
+A fixed rate takes an amount per currency in `values`, and `value` is the fallback. `CreateCommissionRateDTO` doesn’t declare `values` or `rules`, but the module creates both as nested records.
+
+```ts title="src/scripts/seed-commission.ts"
+const flatFee = {
+  name: "Flat fee",
+  type: CommissionRateType.FIXED,
+  value: 3,
+  values: [
+    { currency_code: "usd", amount: 2.5 },
+    { currency_code: "eur", amount: 2 },
+  ],
+  rules: [{ reference: "seller", reference_id: "sel_01JD8Q1234567" }],
 }
+
+await createCommissionRatesWorkflow(container).run({ input: [flatFee] })
 ```
 
-<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 },
-      ],
-    },
-  ],
+Declaring the rate as a variable keeps TypeScript from rejecting the extra `values` and `rules` keys. The result is a flat fee per line item for one seller: 2.5 in USD, 2 in EUR, and 3 in any other currency.
+
+## Change the global commission
+
+The global rate is the one with `is_default: true`. Look it up, then update it with `updateCommissionRatesWorkflow`.
+
+```ts title="src/scripts/seed-commission.ts"
+import { MercurModules } from "@mercurjs/types"
+import { updateCommissionRatesWorkflow } from "@mercurjs/core/workflows"
+
+const commission = container.resolve(MercurModules.COMMISSION)
+const [globalRate] = await commission.listCommissionRates({
+  is_default: true,
+})
+
+await updateCommissionRatesWorkflow(container).run({
+  input: [{ id: globalRate.id, value: 10, include_shipping: true }],
 })
 ```
 
-## Scope the rate
+This raises the baseline to 10% and turns on shipping commission. Only the global rate’s `include_shipping` produces shipping lines.
 
-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).
+## Next steps
 
-<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>
+- [Scope rates with batchCommissionRulesWorkflow](/platform/commission/guides/batch-update-rules)
+- [Recompute existing orders after changing rates](/platform/commission/guides/refresh-order-commission-lines)
+- [See how the winning rate is picked](/platform/commission/concepts/rule-matching)

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

@@ -1,55 +1,124 @@
 ---
 title: "Refresh order commission lines"
 sidebarTitle: "Refresh order lines"
-description: "Recompute an order's commission lines after it changes."
+description: "Recompute commission lines for existing orders, and pass extra data to the commission provider with workflow hooks."
 ---
 
-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.
+Recompute the commission lines of existing orders, for example after you change rates or when you change an order outside Mercur’s own workflows. Mercur already refreshes lines at checkout and on order edits, returns, claims, and exchanges.
 
-## Run the workflow
+<Steps>
+  <Step title="Run the workflow">
+    Pass the ids of the orders to `refreshOrderCommissionLinesWorkflow`. This route refreshes one order.
 
-`refreshOrderCommissionLinesWorkflow` reads each order, resolves the matching
-rate for every item and shipping method, and writes the resulting
-`CommissionLine` records.
+    ```ts title="src/api/admin/orders/[id]/recompute-commission/route.ts"
+    import type {
+      MedusaRequest,
+      MedusaResponse,
+    } from "@medusajs/framework/http"
+    import { refreshOrderCommissionLinesWorkflow } from "@mercurjs/core/workflows"
 
-```ts title="src/api/custom/refresh/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+    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 })
+    }
+    ```
+
+    The workflow returns the lines it wrote for all the orders. It throws if any id doesn’t belong to an order.
+
+  </Step>
+  <Step title="Check the result">
+    Read the lines back through `query.graph`, filtering by the order’s item ids.
+
+    ```ts
+    const { data: lines } = await query.graph({
+      entity: "commission_line",
+      fields: ["item_id", "shipping_method_id", "code", "rate", "amount"],
+      filters: { item_id: ["ordli_01JD8Q1234567"] },
+    })
+    ```
+
+    Item lines carry `item_id`. Shipping lines carry `shipping_method_id` and the description `Shipping Commission`.
+
+  </Step>
+</Steps>
+
+## Backfill existing orders
+
+The workflow takes any number of order ids and resolves them in one batch, so the rates load once per run. For a backfill, page through orders and refresh each page.
+
+```ts title="src/scripts/backfill-commission.ts"
+import type { ExecArgs } from "@medusajs/framework/types"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
 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] },
-  })
+export default async function backfill({ container }: ExecArgs) {
+  const query = container.resolve(ContainerRegistrationKeys.QUERY)
+  const take = 100
+
+  for (let skip = 0; ; skip += take) {
+    const { data } = await query.graph({
+      entity: "order",
+      fields: ["id"],
+      pagination: { skip, take },
+    })
+    if (!data.length) break
 
-  res.json({ commission_lines: result })
+    await refreshOrderCommissionLinesWorkflow(container).run({
+      input: { order_ids: data.map((order) => order.id) },
+    })
+  }
 }
 ```
 
-<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>
+Each page is one workflow run. A refresh replaces lines by item and shipping method, so you can re-run the script safely.
 
-## Idempotency
+## Pass extra data with setCommissionContext
 
-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.
+The `setCommissionContext` hook receives the calculation contexts before they reach the provider. Return a `StepResponse` with new contexts to fill `additional_context` for a custom provider, or return nothing to keep them.
 
-## When it runs automatically
+```ts title="src/workflows/hooks/commission-context.ts"
+import { StepResponse } from "@medusajs/framework/workflows-sdk"
+import { refreshOrderCommissionLinesWorkflow } from "@mercurjs/core/workflows"
+
+refreshOrderCommissionLinesWorkflow.hooks.setCommissionContext(
+  ({ contexts }) =>
+    new StepResponse(
+      contexts.map((context) => ({
+        ...context,
+        additional_context: { tier: "gold" },
+      }))
+    )
+)
+```
+
+Each context already has `order_id`, `seller_id`, `currency_code`, `items`, and `shipping_methods`. Items carry the product’s `tags` and `attribute_value_ids`, which the `system` provider ignores but your own provider can use.
+
+## React with commissionLinesUpserted
+
+The `commissionLinesUpserted` hook runs after the lines are written, as part of the same workflow run. If your handler throws, the run fails, and at checkout that fails the cart completion too.
+
+```ts title="src/workflows/hooks/commission-written.ts"
+import { refreshOrderCommissionLinesWorkflow } from "@mercurjs/core/workflows"
+
+refreshOrderCommissionLinesWorkflow.hooks.commissionLinesUpserted(
+  async ({ order_ids, commission_lines }, { container }) => {
+    const logger = container.resolve("logger")
+    logger.info(
+      `${commission_lines.length} lines for ${order_ids.join(", ")}`
+    )
+  }
+)
+```
 
-You rarely need to call this by hand. Mercur runs it for you:
+Use this hook to sync commission to an external ledger. Use the [order events](/platform/commission/reference/events) instead when your side effect shouldn’t be able to block the refresh.
 
-- **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.
+## Next steps
 
-<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>
+- [What a commission line records](/platform/commission/concepts/order-commission-lines)
+- [Write a custom commission provider](/platform/commission/reference/service)
+- [Hooks of every commission workflow](/platform/commission/reference/workflows)

package/content/platform/commission/overview.mdx

@@ -1,86 +1,94 @@
 ---
-title: "Commission"
+title: "Commissions"
 sidebarTitle: "Overview"
-description: "Configure how the marketplace takes its cut of every seller order."
+description: "Set the share of each sale the marketplace keeps, scope it to sellers and parts of the catalog, and record it per order line."
 ---
 
-Use Mercur to keep financial control over what share of each sale the
-marketplace keeps and each seller earns.
+Use Mercur to decide what share of each sale the marketplace keeps and what 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.
+Commission is the marketplace’s cut of a seller order. You define rates as a percentage or a fixed amount and scope them with rules to sellers, products, types, collections, or categories. When an order is placed, Mercur picks the most specific matching rate for every line item and writes a commission line with the amount. The payout for that order is the order total minus the sum of its commission lines.
+
+<img className="block dark:hidden" src="/images/figures/commission-overview-light.svg" alt="Commission rates behind the commission lines of order #100: the Linen shirt line matches the 12% acme-apparel rate for € 5.64, while the Desk lamp line and the shipping method fall back to the 10% default rate." />
+<img className="hidden dark:block" src="/images/figures/commission-overview-dark.svg" alt="Commission rates behind the commission lines of order #100: the Linen shirt line matches the 12% acme-apparel rate for € 5.64, while the Desk lamp line and the shipping method fall back to the 10% default rate." />
 
 <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.
+  The Commission module owns four data models: `CommissionRate` (`comrate`), `CommissionRule` (`comrule`), `CommissionRateValue` (`comval`), and `CommissionLine` (`comline`). Resolve its service with `MercurModules.COMMISSION` from `@mercurjs/types`.
 </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.
+The Commission module covers configuration, resolution, and the per-order record:
+
+- **Percentage or fixed rates**: a percent of the line subtotal, or a flat amount per line
+- **Per-currency amounts**: a fixed rate holds one amount per currency and falls back to its `value`
+- **Five scoping dimensions**: rules match on `product`, `product_type`, `product_collection`, `product_category`, and `seller`
+- **Most specific wins**: the matching rate scoped on the most dimensions wins, and ties go to the oldest rate
+- **Global commission**: a seeded `is_default` rate that can’t be deleted and is the only rate that commissions shipping
+- **Lines that follow the order**: lines are written at checkout and recomputed on order edits, returns, claims, and exchanges
+- **Exact arithmetic**: amounts are computed with Medusa’s `MathBN` and stored as big numbers
+- **Pluggable calculation**: swap the built-in `system` provider for your own `ICommissionProvider`
+
+## How it works
+
+Commission runs as part of checkout and again whenever the order changes:
+
+1. `completeCartWithSplitOrdersWorkflow` splits the cart into one order per seller.
+2. It runs `refreshOrderCommissionLinesWorkflow` for the new orders as a nested step.
+3. The workflow builds one calculation context per order and passes them to the active provider in one batch.
+4. The `system` provider loads the enabled rates once and picks the winning rate for each item.
+5. The module replaces the order’s commission lines with the new set.
+6. When a payout is created, Mercur subtracts the sum of the order’s commission lines from the order total.
 
 ## Get started
 
-Learn how the domain fits together.
+Learn how rates, rules, and commission lines fit 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.
+    Percentage and fixed rates, per-currency amounts, and the global commission.
   </Card>
   <Card title="Rule matching" icon="sliders" href="/platform/commission/concepts/rule-matching">
-    The five dimensions, most-specific-wins, tie-breaks, and shipping.
+    How Mercur picks one rate for each line, and how shipping is handled.
   </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.
+    What a commission line records and when it’s recomputed.
   </Card>
 </CardGroup>
 
 ## Examples
 
-Build against the Commission domain in your own code.
+Build against commission in your own server 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.
+    Create percentage and fixed rates with `createCommissionRatesWorkflow`.
   </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.
+    Add, change, and remove a rate’s rules in one workflow run.
   </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.
+    Recompute commission for orders and extend the calculation context.
   </Card>
 </CardGroup>
 
 ## Resources
 
-Data models, workflows, service methods, and events for the Commission domain.
+The data models, links, workflows, service methods, and events behind commission.
 
 <CardGroup cols={2}>
   <Card title="Data models" icon="table" href="/platform/commission/reference/data-models">
-    `CommissionRate`, `CommissionRule`, and related entities.
+    Every field of the four commission models.
   </Card>
   <Card title="Links" icon="link" href="/platform/commission/reference/links">
-    How Commission connects to catalog, sellers, and orders.
+    How commission records point at the catalog, sellers, and orders.
   </Card>
   <Card title="Workflows" icon="diagram-project" href="/platform/commission/reference/workflows">
-    Rate, rule, and order-line workflows.
+    Rate, rule, and order-line workflows with their inputs and hooks.
   </Card>
   <Card title="Service" icon="gear" href="/platform/commission/reference/service">
-    Module service methods for working with records directly.
+    Generated and custom service methods, and commission providers.
   </Card>
   <Card title="Events" icon="bell" href="/platform/commission/reference/events">
-    How commission stays in sync with order changes.
+    The order events that trigger a recompute.
   </Card>
 </CardGroup>