@mercurjs/docs 2.2.0-canary.40

package/content/references/modules/seller.mdx

@@ -0,0 +1,175 @@
+---
+title: "Seller module"
+description: "Data models, links, and service methods for the Seller module."
+---
+
+The Seller module owns the marketplace vendor domain: the seller entity and its satellite records (professional details, address, payment details), the seller's team (members and pending invites), and the **order group** — the aggregate that binds the per-seller orders created from a single multi-vendor cart.
+
+For the conceptual introduction, see [Sellers](/rc/learn/sellers), [Seller members](/rc/learn/seller-members), and [Order groups](/rc/learn/order-groups).
+
+## Data models
+
+### `Seller`
+
+Table `seller`, ID prefix `sel`.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | text | Primary key |
+| `name` | text | Unique, searchable |
+| `handle` | text | Unique, URL-friendly; auto-generated from `name` when omitted |
+| `email` | text | Unique, searchable |
+| `phone` | text | Nullable |
+| `description` | text | Nullable |
+| `logo` | text | Nullable |
+| `banner` | text | Nullable |
+| `website_url` | text | Nullable |
+| `external_id` | text | Nullable; unique when set |
+| `currency_code` | text | The seller's single operating currency |
+| `status` | enum | `SellerStatus`, default `pending_approval` |
+| `status_reason` | text | Nullable |
+| `approved_at` | dateTime | Nullable |
+| `rejected_at` | dateTime | Nullable |
+| `is_premium` | boolean | Default `false`; operator-set only |
+| `closed_from` / `closed_to` | dateTime | Nullable; scheduled closure window |
+| `closure_note` | text | Nullable |
+| `metadata` | json | Nullable |
+
+Relations: `professional_details`, `address`, and `payment_details` (one-to-one, deleted with the seller), `members` (many-to-many through `SellerMember`), `member_invites` (one-to-many, deleted with the seller).
+
+### `ProfessionalDetails`
+
+Table `professional_details`, ID prefix `selprodet`. Presence of this record marks the seller as a registered business.
+
+| Field | Type |
+| --- | --- |
+| `corporate_name` | text, nullable |
+| `registration_number` | text, nullable |
+| `tax_id` | text, nullable |
+
+### `SellerAddress`
+
+Table `seller_address`, ID prefix `seladdr`. Fields: `name`, `company`, `first_name`, `last_name`, `address_1`, `address_2`, `city`, `country_code`, `province`, `postal_code`, `phone`, `metadata` — all nullable.
+
+### `PaymentDetails`
+
+Table `payment_details`, ID prefix `selpaydet`. Fields: `country_code`, `holder_name`, `bank_name`, `iban`, `bic`, `routing_number`, `account_number` — all nullable.
+
+### `Member`
+
+Table `member`, ID prefix `mem`. A member is a dashboard user that can belong to one or more sellers.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `email` | text | Unique, searchable |
+| `first_name` / `last_name` | text | Nullable |
+| `locale` | text | Nullable |
+| `is_active` | boolean | Default `true` |
+| `metadata` | json | Nullable |
+
+### `SellerMember`
+
+Table `seller_member`, ID prefix `selmem`. Pivot between `Seller` and `Member`; unique on (`seller_id`, `member_id`).
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `role_id` | text | Nullable; resolved against the RBAC roles module |
+| `is_owner` | boolean | Default `false` |
+| `metadata` | json | Nullable |
+
+### `MemberInvite`
+
+Table `member_invite`, ID prefix `meminv`. Unique on (`email`, `seller_id`) while unaccepted.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `email` | text | Searchable |
+| `token` | text | Signed JWT |
+| `accepted` | boolean | Default `false` |
+| `expires_at` | dateTime | Derived from `invite_valid_duration` |
+| `role_id` | text | Role assigned on acceptance |
+| `metadata` | json | Nullable |
+
+### `OrderGroup`
+
+Table `order_group`, ID prefix `og`. Created when a multi-vendor cart completes.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `display_id` | autoincrement | Shopper-facing number |
+| `cart_id` | text | The originating cart |
+| `customer_id` | text | Nullable |
+| `seller_count` | number | Computed |
+| `total` | bigNumber | Computed across child orders |
+
+## Enums
+
+```ts
+enum SellerStatus {
+  OPEN = "open",
+  PENDING_APPROVAL = "pending_approval",
+  SUSPENDED = "suspended",
+  TERMINATED = "terminated",
+}
+
+enum SellerRole {
+  SELLER_ADMINISTRATION = "role_seller_administration",
+  INVENTORY_MANAGEMENT = "role_seller_inventory_management",
+  ORDER_MANAGEMENT = "role_seller_order_management",
+  ACCOUNTING = "role_seller_accounting",
+  SUPPORT = "role_seller_support",
+}
+```
+
+## Links
+
+The seller is the anchor of the marketplace graph. Nearly every seller-scoped resource is connected through a module link rather than a foreign key:
+
+| Linked entity | Cardinality | Purpose |
+| --- | --- | --- |
+| `Product.product` | many-to-many (`product_seller`) | Selling-eligibility allowlist for [master products](/rc/references/modules/product-edit) |
+| `Order.order` | one seller — many orders | Per-seller child orders |
+| `Payout.payout` | one seller — many payouts | Settlements |
+| `Payout.payoutAccount` | one-to-one | The seller's provider account |
+| `Pricing.priceList` | one seller — many lists | Vendor price lists |
+| `Promotion.promotion` / `Promotion.campaign` | one seller — many | Vendor promotions and campaigns |
+| `Inventory.inventoryItem` | one seller — many items | Vendor inventory |
+| `StockLocation.stockLocation` | one seller — many | Vendor locations |
+| `Fulfillment.shippingProfile` / `shippingOption` / `fulfillmentSet` / `serviceZone` | one seller — many | Vendor shipping setup |
+| `Customer.customer` / `customerGroup` | many-to-many / one seller — many | Vendor customer base |
+| `Product.productCategory` | many-to-many | Categories a seller may sell in |
+
+Order groups carry two additional links: a read-only link to the originating `Cart` (via `cart_id`) and a list link to the child `Order` records (table `order_group_order`). The `SellerMember.role_id` field is a read-only link into the RBAC roles module.
+
+## Service
+
+`SellerModuleService` extends `MedusaService` with auto-generated CRUD for all models above, plus:
+
+| Method | Behavior |
+| --- | --- |
+| `createSellers(data)` / `updateSellers(data)` | Validates the handle and auto-generates it from `name` when missing |
+| `upsertMembers(data)` | Dedupes by email, creates missing members, backfills empty names; returns members in input order |
+| `createMemberInvites(data)` | Rejects emails that already belong to the seller; issues a JWT token with an expiry |
+| `validateMemberInviteToken(token)` | Verifies the JWT and rejects accepted or expired invites |
+| `listOrderGroups` / `listAndCountOrderGroups` / `retrieveOrderGroup` | Custom repository-backed reads that resolve the computed `seller_count` and `total` fields |
+
+## Module options
+
+| Option | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `invite_valid_duration` | number (seconds) | 7 days | Member invite lifetime |
+| `jwt_secret` | string | project `http.jwtSecret` | Signs invite tokens |
+| `vendor_url` | string | `MERCUR_VENDOR_URL` env var | Vendor dashboard base URL used in invite links |
+
+## Related endpoints
+
+- [Admin API — sellers, members, order groups](/rc/references/api/admin)
+- [Vendor API — sellers, members](/rc/references/api/vendor)
+- [Store API — public seller storefronts](/rc/references/api/store)
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Commission module" href="/rc/references/modules/commission" />
+  <Card title="Payout module" href="/rc/references/modules/payout" />
+</CardGroup>

package/content/references/overview.mdx

@@ -0,0 +1,70 @@
+---
+title: "References"
+description: "Technical references for Mercur's modules, HTTP APIs, workflows, and configuration."
+---
+
+This section is the technical contract of the Mercur core plugin. Where the [Learn](/rc/learn/introduction) tab explains concepts, these pages document the exact surface: data models and their fields, module links, service methods, HTTP routes, workflow names, and configuration options.
+
+## Modules
+
+Every marketplace capability ships as a Medusa module inside `@mercurjs/core`. Each reference covers the module's data models, enums, links to Medusa core entities, service methods, and options.
+
+<CardGroup cols={3}>
+  <Card title="Seller" href="/rc/references/modules/seller">
+    Sellers, members, invites, and order groups.
+  </Card>
+  <Card title="Commission" href="/rc/references/modules/commission">
+    Commission rates, rules, and per-order commission lines.
+  </Card>
+  <Card title="Payout" href="/rc/references/modules/payout">
+    Payout accounts, onboarding, payouts, and the provider interface.
+  </Card>
+  <Card title="Offer" href="/rc/references/modules/offer">
+    Per-seller listings binding a variant to SKU, price, and inventory.
+  </Card>
+  <Card title="Product Attribute" href="/rc/references/modules/product-attribute">
+    Configurable attributes, values, and variant axes on native product options.
+  </Card>
+  <Card title="Product Edit" href="/rc/references/modules/product-edit">
+    Product change requests and the approval queue.
+  </Card>
+  <Card title="Media" href="/rc/references/modules/media">
+    Image galleries, thumbnails, banners, and icons for categories and collections.
+  </Card>
+  <Card title="Search" href="/rc/references/modules/search">
+    Provider-agnostic search with the built-in Orama provider.
+  </Card>
+  <Card title="Custom Fields" href="/rc/references/modules/custom-fields">
+    Extra columns on any entity without a custom module.
+  </Card>
+</CardGroup>
+
+## HTTP API
+
+Mercur extends the Medusa server with three route surfaces. Start with the conventions page — authentication, seller scoping, and pagination work the same way across all of them.
+
+<CardGroup cols={2}>
+  <Card title="API conventions" href="/rc/references/api/conventions">
+    Authentication, seller scoping, pagination, field selection, and webhooks.
+  </Card>
+  <Card title="Admin API" href="/rc/references/api/admin">
+    Operator routes under <code>/admin/*</code>.
+  </Card>
+  <Card title="Vendor API" href="/rc/references/api/vendor">
+    Seller-scoped routes under <code>/vendor/*</code>.
+  </Card>
+  <Card title="Store API" href="/rc/references/api/store">
+    Storefront routes under <code>/store/*</code>.
+  </Card>
+</CardGroup>
+
+## Workflows and configuration
+
+<CardGroup cols={2}>
+  <Card title="Workflows" href="/rc/references/workflows">
+    Every workflow exported by <code>@mercurjs/core</code>, grouped by domain.
+  </Card>
+  <Card title="Configuration" href="/rc/references/configuration">
+    <code>withMercur()</code>, environment variables, and provider options.
+  </Card>
+</CardGroup>

package/content/references/workflows/cart/add-seller-shipping-method-to-cart.mdx

@@ -0,0 +1,44 @@
+---
+title: "addSellerShippingMethodToCartWorkflow"
+description: "Add shipping methods to a cart, replacing only the same seller's existing methods."
+---
+
+Seller-aware variant of Medusa's `addShippingMethodToCartWorkflow`. Validates the requested options against the cart and their calculated prices, then swaps shipping methods per seller: existing methods belonging to the sellers whose options are being added are removed, while other sellers' methods stay untouched — so a multi-seller cart keeps one shipping method per seller. Refreshes cart items afterwards and emits `cart.updated`. Triggered by `POST /store/carts/:id/shipping-methods`.
+
+## Usage
+
+```ts
+import { addSellerShippingMethodToCartWorkflow } from "@mercurjs/core/workflows"
+
+await addSellerShippingMethodToCartWorkflow(container).run({
+  input: {
+    cart_id: "cart_123",
+    options: [{ id: "so_123" }],
+  },
+})
+```
+
+## Input
+
+<ParamField body="cart_id" type="string" required>The cart to add shipping methods to.</ParamField>
+<ParamField body="options" type="object[]" required>Shipping options to add as methods.
+  <Expandable title="properties">
+    <ParamField body="id" type="string" required>The shipping option ID; must have a calculated price for the cart.</ParamField>
+    <ParamField body="data" type="object">Custom method data validated by the fulfillment provider.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">No return value; the cart's shipping methods are replaced per seller as a side effect.</ResponseField>
+
+## Hooks
+
+- `validate` — runs after the cart is loaded with `{ input, cart }`.
+
+```ts
+addSellerShippingMethodToCartWorkflow.hooks.validate(async ({ input, cart }) => {
+  // throw to reject the shipping method
+})
+```

package/content/references/workflows/cart/complete-cart-with-split-orders.mdx

@@ -0,0 +1,36 @@
+---
+title: "completeCartWithSplitOrdersWorkflow"
+description: "Complete a multi-seller cart by splitting it into per-seller orders under an order group."
+---
+
+Mercur's replacement for Medusa's `completeCartWorkflow` and the heart of multi-vendor checkout. It groups the cart's items by the seller behind each item's offer, creates one order per seller (each carrying only that seller's items, shipping methods, addresses, and promotion adjustments), and wraps them in a single `OrderGroup` the shopper tracks as one purchase. Along the way it validates seller items and shipping coverage, mirrors line-item ↔ offer links onto the new order items, reserves offer inventory, registers promotion usage, links orders to the cart, sellers, payment collection, and order group, authorizes the single payment session, distributes captured amounts proportionally as order transactions, and refreshes each order's commission lines via `refreshOrderCommissionLinesWorkflow`. The run is idempotent per cart — an existing order group for the cart is returned instead of re-creating orders. Emits `order.placed` (one entry per child order) and `order_group.created`. Triggered by `POST /store/carts/:id/complete`.
+
+## Usage
+
+```ts
+import { completeCartWithSplitOrdersWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await completeCartWithSplitOrdersWorkflow(container).run({
+  input: { cart_id: "cart_123" },
+})
+```
+
+## Input
+
+<ParamField body="cart_id" type="string" required>The cart to complete; must have an authorized-able payment session and seller-scoped shipping methods covering every seller in the cart.</ParamField>
+
+## Result
+
+<ResponseField name="result.order_group_id" type="string">ID of the order group wrapping the per-seller orders — either newly created or the one already created for this cart.</ResponseField>
+
+## Hooks
+
+- `validate` — runs after the cart is loaded (before any orders are created) with `{ input, cart }`.
+- `beforePaymentAuthorization` — runs after orders and links are created, right before the payment session is authorized, with `{ input }`.
+- `orderGroupCreated` — runs at the end of the creation branch with `{ order_group_id, cart_id }`.
+
+```ts
+completeCartWithSplitOrdersWorkflow.hooks.validate(async ({ input, cart }) => {
+  // throw to block checkout
+})
+```

package/content/references/workflows/cart/list-seller-shipping-options-for-cart.mdx

@@ -0,0 +1,39 @@
+---
+title: "listSellerShippingOptionsForCartWorkflow"
+description: "List available shipping options for a cart, grouped by seller."
+---
+
+Resolves the sellers behind the cart's offers, finds their stock locations valid for the cart's sales channel, and queries shipping options in those locations' fulfillment sets with cart-scoped pricing. Each option carries its calculated `amount`, `is_tax_inclusive`, and an `insufficient_inventory` flag when the seller's location can't cover the cart quantities. Options are translated to the cart locale and returned keyed by seller ID. Triggered by `GET /store/shipping-options`.
+
+## Usage
+
+```ts
+import { listSellerShippingOptionsForCartWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await listSellerShippingOptionsForCartWorkflow(container).run({
+  input: { cart_id: "cart_123" },
+})
+```
+
+## Input
+
+<ParamField body="cart_id" type="string" required>The cart to list options for; must have `sales_channel_id`, `region_id`, and `currency_code` set.</ParamField>
+<ParamField body="is_return" type="boolean">List return shipping options instead; defaults to `false`.</ParamField>
+<ParamField body="enabled_in_store" type="boolean">Only options enabled in the storefront; defaults to `true`.</ParamField>
+<ParamField body="fields" type="string[]">Extra shipping-option fields to retrieve on top of the defaults.</ParamField>
+<ParamField body="additional_data" type="object">Custom data passed through to the workflow hooks.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="Record<string, ShippingOptionDTO[]>">Map of seller ID to that seller's priced shipping options, each extended with `amount`, `is_tax_inclusive`, and `insufficient_inventory`.</ResponseField>
+
+## Hooks
+
+- `setPricingContext` — runs with `{ cart, fulfillmentSetIds, additional_data }`; return a record to merge into the price calculation context.
+- `setShippingOptionsContext` — runs with the same payload; return a record to merge into the shipping-option rule context.
+
+```ts
+listSellerShippingOptionsForCartWorkflow.hooks.setPricingContext(async ({ cart }) => {
+  return { customer_tier: "vip" }
+})
+```

package/content/references/workflows/cart/update-cart-seller-promotions.mdx

@@ -0,0 +1,42 @@
+---
+title: "updateCartSellerPromotionsWorkflow"
+description: "Apply, remove, or replace promotion codes on a cart with seller-scoped adjustments."
+---
+
+Seller-aware variant of Medusa's `updateCartPromotionsWorkflow`. Computes promotion actions for the requested codes, then prepares line-item and shipping-method adjustments so each promotion only discounts the owning seller's items, before creating/removing adjustments and syncing the cart's applied promotions. Optionally refreshes the payment collection. Triggered by `POST /store/carts/:id/promotions`.
+
+## Usage
+
+```ts
+import { updateCartSellerPromotionsWorkflow } from "@mercurjs/core/workflows"
+
+await updateCartSellerPromotionsWorkflow(container).run({
+  input: {
+    cart_id: "cart_123",
+    promo_codes: ["SUMMER10"],
+    action: "add",
+  },
+})
+```
+
+## Input
+
+<ParamField body="cart_id" type="string" required>The cart to update promotions on.</ParamField>
+<ParamField body="promo_codes" type="string[]">Promotion codes to apply; defaults to `[]`.</ParamField>
+<ParamField body="action" type="string">One of `add`, `remove`, `replace`; defaults to `add`.</ParamField>
+<ParamField body="cart" type="object">Preloaded cart data; skips the internal cart fetch when provided.</ParamField>
+<ParamField body="force_refresh_payment_collection" type="boolean">Refresh the cart's payment collection after adjustments change.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">No return value; the cart's adjustments and applied promotions are updated as a side effect.</ResponseField>
+
+## Hooks
+
+- `validate` — runs after the cart is loaded with `{ input, cart }`.
+
+```ts
+updateCartSellerPromotionsWorkflow.hooks.validate(async ({ input, cart }) => {
+  // throw to reject the promotion change
+})
+```

package/content/references/workflows/commission/batch-commission-rules.mdx

@@ -0,0 +1,45 @@
+---
+title: "batchCommissionRulesWorkflow"
+description: "Create, update, and delete a commission rate's rules in one call."
+---
+
+Runs create, update, and delete operations on a commission rate's rules in parallel. Rules bind a rate to a reference (e.g. a seller, category, or product type) so the rate applies when an order line matches. Triggered by `POST /admin/commission-rates/:id/rules`.
+
+## Usage
+
+```ts
+import { batchCommissionRulesWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await batchCommissionRulesWorkflow(container).run({
+  input: {
+    commission_rate_id: "comrate_123",
+    create: [{ reference: "seller", reference_id: "sel_123" }],
+    update: [{ id: "comrule_456", reference_id: "sel_789" }],
+    delete: ["comrule_999"],
+  },
+})
+```
+
+## Input
+
+<ParamField body="commission_rate_id" type="string" required>The commission rate the rules belong to.</ParamField>
+<ParamField body="create" type="object[]">Rules to create.
+  <Expandable title="properties">
+    <ParamField body="reference" type="string" required>Entity type the rule targets (e.g. `seller`, `product_category`, `product_type`).</ParamField>
+    <ParamField body="reference_id" type="string" required>ID of the referenced entity.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="update" type="object[]">Rules to update.
+  <Expandable title="properties">
+    <ParamField body="id" type="string" required>The rule to update.</ParamField>
+    <ParamField body="reference" type="string">New reference type.</ParamField>
+    <ParamField body="reference_id" type="string">New referenced entity ID.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="delete" type="string[]">IDs of rules to delete.</ParamField>
+
+## Result
+
+<ResponseField name="result.created" type="CommissionRuleDTO[]">The created rules.</ResponseField>
+<ResponseField name="result.updated" type="CommissionRuleDTO[]">The updated rules.</ResponseField>
+<ResponseField name="result.deleted" type="string[]">IDs of the deleted rules.</ResponseField>

package/content/references/workflows/commission/create-commission-rates.mdx

@@ -0,0 +1,41 @@
+---
+title: "createCommissionRatesWorkflow"
+description: "Create one or more commission rates."
+---
+
+Creates commission rates — the fee definitions (flat or percentage) applied to seller orders. A unique `code` is auto-generated from the name when not provided. Triggered by `POST /admin/commission-rates`.
+
+## Usage
+
+```ts
+import { createCommissionRatesWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await createCommissionRatesWorkflow(container).run({
+  input: [
+    {
+      name: "Default commission",
+      type: "percentage",
+      value: 10,
+      is_default: true,
+    },
+  ],
+})
+```
+
+## Input
+
+The input is an array of commission rates to create.
+
+<ParamField body="name" type="string" required>Display name of the rate.</ParamField>
+<ParamField body="type" type="string" required>One of `fixed`, `percentage`.</ParamField>
+<ParamField body="value" type="number" required>Rate value — a percentage for `percentage`, an amount for `fixed`.</ParamField>
+<ParamField body="code" type="string">Unique code; auto-generated from the name when omitted.</ParamField>
+<ParamField body="currency_code" type="string | null">Currency of a `fixed` rate.</ParamField>
+<ParamField body="include_tax" type="boolean">Include tax totals in the commission base.</ParamField>
+<ParamField body="include_shipping" type="boolean">Also apply the rate to shipping methods.</ParamField>
+<ParamField body="is_enabled" type="boolean">Whether the rate is active.</ParamField>
+<ParamField body="is_default" type="boolean">Marks the rate as the platform-wide fallback.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="CommissionRateDTO[]">The created commission rates.</ResponseField>

package/content/references/workflows/commission/delete-commission-rates.mdx

@@ -0,0 +1,34 @@
+---
+title: "deleteCommissionRatesWorkflow"
+description: "Soft-delete commission rates after validating they can be removed."
+---
+
+Validates the rates are deletable, then soft-deletes them. Deletion is reversible on workflow failure (compensation restores the rates). Triggered by `DELETE /admin/commission-rates/:id`.
+
+## Usage
+
+```ts
+import { deleteCommissionRatesWorkflow } from "@mercurjs/core/workflows"
+
+await deleteCommissionRatesWorkflow(container).run({
+  input: { ids: ["comrate_123"] },
+})
+```
+
+## Input
+
+<ParamField body="ids" type="string[]" required>IDs of the commission rates to delete.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">No return value; the rates are soft-deleted.</ResponseField>
+
+## Hooks
+
+- `commissionRatesDeleted` — runs after deletion with `{ ids }`.
+
+```ts
+deleteCommissionRatesWorkflow.hooks.commissionRatesDeleted(async ({ ids }) => {
+  // react to deleted rates
+})
+```

package/content/references/workflows/commission/refresh-order-commission-lines.mdx

@@ -0,0 +1,30 @@
+---
+title: "refreshOrderCommissionLinesWorkflow"
+description: "Recompute the commission lines for one or more orders."
+---
+
+Loads each order with its items, products, sellers, and shipping methods, evaluates the matching commission rates, and upserts a commission line per item and shipping method (delete-then-insert, so re-running is idempotent). Runs inside `completeCartWithSplitOrdersWorkflow` after orders are created, and again from the `order-edit-confirmed` subscriber on order edits, returns, claims, and exchanges.
+
+## Usage
+
+```ts
+import { refreshOrderCommissionLinesWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await refreshOrderCommissionLinesWorkflow(container).run({
+  input: { order_ids: ["order_123"] },
+})
+```
+
+## Input
+
+<ParamField body="order_ids" type="string[]" required>IDs of the orders to recompute commission lines for; fails if any order is not found.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="CommissionLineDTO[]">The upserted commission lines.</ResponseField>
+<ResponseField name="result[].item_id" type="string | null">The order line item the commission applies to.</ResponseField>
+<ResponseField name="result[].shipping_method_id" type="string | null">The shipping method the commission applies to.</ResponseField>
+<ResponseField name="result[].commission_rate_id" type="string | null">The rate that produced the line.</ResponseField>
+<ResponseField name="result[].code" type="string">Code of the applied rate.</ResponseField>
+<ResponseField name="result[].rate" type="number">Rate value applied.</ResponseField>
+<ResponseField name="result[].amount" type="number">Commission amount in the order currency.</ResponseField>

package/content/references/workflows/commission/update-commission-rates.mdx

@@ -0,0 +1,35 @@
+---
+title: "updateCommissionRatesWorkflow"
+description: "Update one or more commission rates."
+---
+
+Applies partial updates to existing commission rates by ID. Triggered by `POST /admin/commission-rates/:id`.
+
+## Usage
+
+```ts
+import { updateCommissionRatesWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await updateCommissionRatesWorkflow(container).run({
+  input: [{ id: "comrate_123", value: 12, is_enabled: true }],
+})
+```
+
+## Input
+
+The input is an array of commission rate updates.
+
+<ParamField body="id" type="string" required>The commission rate to update.</ParamField>
+<ParamField body="name" type="string">Display name of the rate.</ParamField>
+<ParamField body="code" type="string">Unique code of the rate.</ParamField>
+<ParamField body="type" type="string">One of `fixed`, `percentage`.</ParamField>
+<ParamField body="value" type="number">Rate value — a percentage for `percentage`, an amount for `fixed`.</ParamField>
+<ParamField body="currency_code" type="string | null">Currency of a `fixed` rate.</ParamField>
+<ParamField body="include_tax" type="boolean">Include tax totals in the commission base.</ParamField>
+<ParamField body="include_shipping" type="boolean">Also apply the rate to shipping methods.</ParamField>
+<ParamField body="is_enabled" type="boolean">Whether the rate is active.</ParamField>
+<ParamField body="is_default" type="boolean">Marks the rate as the platform-wide fallback.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="CommissionRateDTO[]">The updated commission rates.</ResponseField>

package/content/references/workflows/media/set-category-images.mdx

@@ -0,0 +1,41 @@
+---
+title: "setCategoryImagesWorkflow"
+description: "Replace a category's media gallery and icon, enforcing single thumbnail/banner."
+---
+
+Replaces a product category's media. When `media` is provided, the entire existing gallery is swapped for the new list; when `icon` is provided, the existing icon image is swapped (pass `null` to clear it). Omitted fields are left untouched. At most one image keeps `is_thumbnail` and one keeps `is_banner` — the first flagged entry wins and later flags are silently dropped. Usually invoked through the `createProductCategoryWithImagesWorkflow`, `updateProductCategoryWithImagesWorkflow`, and `deleteProductCategoryWithImagesWorkflow` wrappers behind the `/admin/product-categories` routes.
+
+## Usage
+
+```ts
+import { setCategoryImagesWorkflow } from "@mercurjs/core/workflows"
+
+await setCategoryImagesWorkflow(container).run({
+  input: {
+    category_id: "pcat_123",
+    media: [
+      { url: "https://cdn.example.com/hero.jpg", is_banner: true },
+      { url: "https://cdn.example.com/thumb.jpg", is_thumbnail: true },
+    ],
+    icon: "https://cdn.example.com/icon.svg",
+  },
+})
+```
+
+## Input
+
+<ParamField body="category_id" type="string" required>The category whose images are replaced.</ParamField>
+<ParamField body="media" type="CategoryMediaInput[]">
+  New gallery; replaces all existing non-icon images (pass `[]` to clear).
+  <Expandable title="properties">
+    <ParamField body="url" type="string" required>Public URL of the image.</ParamField>
+    <ParamField body="is_thumbnail" type="boolean">Mark as the thumbnail; only the first flagged image is honoured.</ParamField>
+    <ParamField body="is_banner" type="boolean">Mark as the banner; only the first flagged image is honoured.</ParamField>
+    <ParamField body="rank" type="number">Sort rank; defaults to the array index.</ParamField>
+  </Expandable>
+</ParamField>
+<ParamField body="icon" type="string | null">New icon URL; `null` removes the current icon, omit to keep it.</ParamField>
+
+## Result
+
+<ResponseField name="result" type="void">No return value.</ResponseField>