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

package/content/platform/order-group/guides/split-a-cart.mdx

@@ -1,58 +1,133 @@
 ---
-title: "Split a cart into orders"
+title: "Split a cart into an order group"
 sidebarTitle: "Split a cart"
-description: "Complete a multi-seller cart into a group of per-seller orders with completeCartWithSplitOrdersWorkflow."
+description: "Run completeCartWithSplitOrdersWorkflow from your own code and change the split with its validate and setOrderStatus hooks."
 ---
 
-In this guide, you'll learn how the checkout split works and how to run it from
-your own server code, such as a custom complete-cart route.
+Run the checkout split yourself when you build a custom completion flow, or hook into it when you need to block a checkout or set the initial status of each seller’s order.
 
-Mercur replaces Medusa's single-order checkout with
-`completeCartWithSplitOrdersWorkflow`. It takes a cart that may hold offers from
-several sellers, creates one order per seller, and wraps them in an `OrderGroup`.
+## Before you begin
 
-## Run the workflow
+You need the following:
 
-```ts title="src/api/store/carts/[id]/complete/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { completeCartWithSplitOrdersWorkflow } from "@mercurjs/core/workflows"
+- **A cart ready to complete**: items bought through offers, a shipping method for each seller that ships, and a payment session
+- **Mercur’s cart completion in place**: Mercur’s cart completion route already runs this workflow, so you only need your own route for a custom flow
 
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
-  const { result } = await completeCartWithSplitOrdersWorkflow(req.scope).run({
-    input: { cart_id: req.params.id },
-  })
+## Complete a cart from a custom route
+
+<Steps>
+  <Step title="Run the workflow">
+    Call `completeCartWithSplitOrdersWorkflow` with the cart id. Set `throwOnError: false` so you can handle payment errors yourself.
+
+    ```ts title="src/api/store/carts/[id]/place/route.ts"
+    import type {
+      MedusaRequest,
+      MedusaResponse,
+    } from "@medusajs/framework/http"
+    import {
+      completeCartWithSplitOrdersWorkflow,
+    } from "@mercurjs/core/workflows"
+
+    export async function POST(req: MedusaRequest, res: MedusaResponse) {
+      const { result, errors } = await completeCartWithSplitOrdersWorkflow(
+        req.scope
+      ).run({
+        input: { cart_id: req.params.id },
+        throwOnError: false,
+      })
+
+      if (errors?.[0]) {
+        throw errors[0].error
+      }
+
+      res.json({ order_group_id: result.order_group_id })
+    }
+    ```
+
+    The workflow returns `{ order_group_id }`. It runs once per cart: a second call for the same cart returns the existing group’s id.
+  </Step>
+  <Step title="Return the group to the shopper">
+    Load the group with `query.graph` and send it back instead of the bare id:
+
+    ```ts
+    const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
+
+    const { data: [order_group] } = await query.graph({
+      entity: "order_group",
+      fields: ["id", "display_id", "total", "orders.id", "orders.total"],
+      filters: { id: result.order_group_id },
+    })
+    ```
+
+    `ContainerRegistrationKeys` comes from `@medusajs/framework/utils`.
+  </Step>
+</Steps>
+
+## Handle a failed payment authorization
+
+The workflow authorizes the payment session after it creates the orders. If authorization fails, the workflow rolls back: it deletes the group, and Medusa’s steps undo the orders, links, and reservations. Mercur’s own route answers `PAYMENT_AUTHORIZATION_ERROR` and `PAYMENT_REQUIRES_MORE_ERROR` with a `200` that carries the cart and the error, so the storefront can retry payment. Do the same in a custom route:
+
+```ts
+import { MedusaError } from "@medusajs/framework/utils"
 
-  res.json({ order_group_id: result.order_group_id })
+const retryable: string[] = [
+  MedusaError.Types.PAYMENT_AUTHORIZATION_ERROR,
+  MedusaError.Types.PAYMENT_REQUIRES_MORE_ERROR,
+]
+
+if (errors?.[0] && retryable.includes(errors[0].error?.type)) {
+  res.json({ type: "cart", error: errors[0].error.message })
+  return
 }
 ```
 
-The workflow is idempotent per cart: if a group already exists for the cart it
-returns the existing `order_group_id` instead of splitting again. It acquires a
-lock on the cart id for the duration of the split so concurrent completions can't
-create duplicate orders.
+Throw every other error so Medusa’s error handler responds with the matching status.
+
+## Block a checkout with the validate hook
+
+The `validate` hook runs before the split and receives the workflow `input` and the `cart`. Throw to stop the checkout:
+
+```ts title="src/workflows/hooks/validate-split-cart.ts"
+import { MedusaError } from "@medusajs/framework/utils"
+import { completeCartWithSplitOrdersWorkflow } from "@mercurjs/core/workflows"
+
+completeCartWithSplitOrdersWorkflow.hooks.validate(async ({ cart }) => {
+  if (!cart.email) {
+    throw new MedusaError(
+      MedusaError.Types.INVALID_DATA,
+      "Add an email address before you complete the cart"
+    )
+  }
+})
+```
+
+The hook runs on every cart completion, including completions started by a payment webhook through `processPaymentWorkflow`.
+
+## Set the initial order status with setOrderStatus
 
-<Note>
-  Line items are grouped by `item.offer.seller_id`. Sellers sell against the
-  shared master catalog through **offers**, so a line item's seller comes from
-  its offer, never from product ownership.
-</Note>
+Child orders start as `pending`. Return a status from the `setOrderStatus` hook to change that, for example when sellers must accept an order before they fulfill it:
+
+```ts title="src/workflows/hooks/set-split-order-status.ts"
+import { OrderStatus } from "@medusajs/framework/utils"
+import { StepResponse } from "@medusajs/framework/workflows-sdk"
+import { completeCartWithSplitOrdersWorkflow } from "@mercurjs/core/workflows"
+
+completeCartWithSplitOrdersWorkflow.hooks.setOrderStatus(async () => {
+  return new StepResponse({
+    status: OrderStatus.REQUIRES_ACTION,
+    status_by_seller_id: { sel_01JD8Q1234567: OrderStatus.PENDING },
+  })
+})
+```
 
-## What happens during the split
+`status` applies to every child order. `status_by_seller_id` overrides it for the sellers you list. Return nothing to keep `pending`.
 
-For the cart, the workflow validates payments and per-seller shipping, then in a
-single transaction:
+## React to the new group
 
-- creates the parent `OrderGroup` (`customer_id`, `cart_id`)
-- creates one child `Order` per seller from that seller's items and shipping
-- links each order to the group, its seller, and the originating cart
-- mirrors line-item → offer links, reserves offer inventory, and splits payment captures proportionally
-- refreshes commission lines per order and marks the cart `completed_at`
+The split emits `order_group.created` with the group id, and `order.placed` once for each child order. Subscribe to the first for purchase-level work, such as a single confirmation email, and to the second for per-seller work. The [event reference](/platform/order-group/reference/events) has a subscriber example.
 
-Finally it emits `order.placed` for the created orders and `order_group.created`
-for the group.
+## Next steps
 
-<Tip>
-  The workflow exposes hooks `validate`, `beforePaymentAuthorization`, and
-  `orderGroupCreated`, so you can inject marketplace-specific logic around the
-  split without forking it.
-</Tip>
+- [How the split assigns items, shipping, and promotions](/platform/order-group/concepts/order-splitting)
+- [`completeCartWithSplitOrdersWorkflow` reference](/platform/order-group/reference/workflows#completecartwithsplitordersworkflow)
+- [Retrieve the new group](/platform/order-group/guides/retrieve-an-order-group)

package/content/platform/order-group/overview.mdx

@@ -1,83 +1,93 @@
 ---
-title: "Order Group"
+title: "Order groups"
 sidebarTitle: "Overview"
-description: "Wrap a multi-seller cart into one shopper-facing order made of independent per-seller orders."
+description: "Turn a cart with items from several sellers into per-seller orders under one group the shopper can track."
 ---
 
-Use Order Groups to turn a single customer cart that spans multiple sellers into
-one coherent order for the shopper.
+Use order groups to give the shopper one purchase while each seller gets an order of their own.
 
-A marketplace cart can contain offers from several sellers at once. On checkout,
-Mercur splits that cart into one child order per seller and wraps them in an
-**Order Group**. This is the aggregate the shopper sees as "their order". Each
-child order is then fulfilled, returned, and refunded independently, while the
-group gives you a single handle over the whole purchase.
+A marketplace cart can hold offers from several sellers. At checkout, Mercur creates one child order per seller and wraps them in an order group. The group is the record the shopper sees as “my order”, while each seller fulfills, returns, and refunds their own child order. The group stores almost nothing itself: its seller count and total are summed from the child orders every time you read it.
+
+<img className="block dark:hidden" src="/images/figures/order-group-overview-light.svg" alt="The order_group record og_01JD8Q1234567 in front, with display_id 98, its customer and read-only cart link, and computed seller_count 2 and total 87.00. Behind it, the order_group_order link lists the two child orders it sums: 47.00 for ACME and 40.00 for GLOBEX." />
+<img className="hidden dark:block" src="/images/figures/order-group-overview-dark.svg" alt="The order_group record og_01JD8Q1234567 in front, with display_id 98, its customer and read-only cart link, and computed seller_count 2 and total 87.00. Behind it, the order_group_order link lists the two child orders it sums: 47.00 for ACME and 40.00 for GLOBEX." />
 
 <Note>
-  An order group is the `OrderGroup` entity. It lives in the **Seller module**
-  (id prefix `og`), not a module of its own. There is no `ORDER_GROUP` module
-  key. Resolve its service through `MercurModules.SELLER`.
+  An order group is the `OrderGroup` data model (id prefix `og`). It belongs to the Seller module, not a module of its own, so there is no `ORDER_GROUP` key. Resolve its service with `MercurModules.SELLER`.
 </Note>
 
 ## Key features
 
-- **Multi-seller checkout:** one cart with offers from many sellers becomes one group of per-seller orders.
-- **Human-readable id:** an auto-incrementing `display_id` the shopper and operator can reference.
-- **Immutable cart link:** a read-only `cart_id` back to the originating cart. Carts are frozen after checkout.
-- **Computed totals:** `seller_count` and `total` are derived at query time, never stored.
-- **Independent child orders:** fulfillment, returns, and refunds happen per seller order.
-- **Scoped visibility:** admins see every group platform-wide. Vendors see only their slice.
+Order groups cover a multi-seller purchase from checkout to the order history:
+
+- **Split checkout**: `completeCartWithSplitOrdersWorkflow` turns one cart into one order per seller under a single group
+- **One group per cart**: completing the same cart twice returns the existing group instead of splitting again
+- **Readable reference**: an auto-incrementing `display_id` that shoppers and operators can quote
+- **Frozen cart link**: a read-only `cart_id` that points at the completed cart
+- **Live totals**: `seller_count` and `total` are computed from the child orders at query time, never stored
+- **Derived child statuses**: the read workflows add `payment_status` and `fulfillment_status` to every child order
+- **Seller scoping**: the list workflow can trim each group down to one seller’s orders
+
+## How it works
+
+A group comes to life when a cart completes:
+
+1. The shopper completes a cart that holds offers from ACME and GLOBEX.
+2. `completeCartWithSplitOrdersWorkflow` groups the line items by `item.offer.seller_id`.
+3. It creates one `OrderGroup` and one child `Order` per seller, then links them.
+4. It authorizes the cart’s payment and refreshes commission lines for each order.
+5. It emits `order.placed` for each child order and `order_group.created` for the group.
+6. When you read the group, the Seller module sums its child orders into `seller_count` and `total`.
 
 ## Get started
 
-Learn how the domain fits together.
+Learn how the group, the split, and the computed totals fit together.
 
 <CardGroup cols={2}>
   <Card title="The order group" icon="layer-group" href="/platform/order-group/concepts/the-order-group">
-    The aggregate entity, its `display_id`, and the read-only cart link.
+    The record over a multi-seller purchase, its `display_id`, and the cart link.
   </Card>
   <Card title="Order splitting" icon="scissors" href="/platform/order-group/concepts/order-splitting">
-    How a multi-seller cart is split into per-seller child orders.
+    How checkout turns one cart into one order per seller.
   </Card>
   <Card title="Computed totals" icon="calculator" href="/platform/order-group/concepts/computed-totals">
-    Why `seller_count` and `total` are calculated at query time.
+    Where `seller_count`, `total`, and child order statuses come from.
   </Card>
 </CardGroup>
 
 ## Examples
 
-Build against Order Groups in your own code.
+Build against order groups in your own server code.
 
 <CardGroup cols={2}>
   <Card title="Retrieve an order group" icon="magnifying-glass" href="/platform/order-group/guides/retrieve-an-order-group">
-    Load a group and its aggregated child orders.
+    Load one group with its child orders and their statuses.
   </Card>
   <Card title="List order groups" icon="list" href="/platform/order-group/guides/list-order-groups">
-    Page through groups, optionally scoped to a seller.
+    Filter, page, and scope groups to a seller.
   </Card>
   <Card title="Split a cart" icon="scissors" href="/platform/order-group/guides/split-a-cart">
-    Complete a multi-seller cart into a group of orders.
+    Complete a cart into a group and hook into the split.
   </Card>
 </CardGroup>
 
 ## Resources
 
-Data models, links, workflows, service methods, and events for Order Groups.
+The data model, links, workflows, service methods, and events behind order groups.
 
 <CardGroup cols={2}>
   <Card title="Data models" icon="table" href="/platform/order-group/reference/data-models">
-    The `OrderGroup` entity and its fields.
+    The `OrderGroup` model, its fields, and indexes.
   </Card>
   <Card title="Links" icon="link" href="/platform/order-group/reference/links">
-    How order groups link to carts, orders, sellers, and offers.
+    How a group connects to its cart, orders, sellers, and offers.
   </Card>
   <Card title="Workflows" icon="diagram-project" href="/platform/order-group/reference/workflows">
-    Splitting, retrieving, and listing order groups.
+    The checkout split, the read workflows, and their hooks.
   </Card>
   <Card title="Service" icon="gear" href="/platform/order-group/reference/service">
-    Seller module methods for working with groups directly.
+    Seller module methods for order group records.
   </Card>
   <Card title="Events" icon="bell" href="/platform/order-group/reference/events">
-    Events emitted as order groups are created.
+    The events emitted when a cart splits into a group.
   </Card>
 </CardGroup>

package/content/platform/order-group/reference/data-models.mdx

@@ -1,40 +1,57 @@
 ---
-title: "Data models"
+title: "Order group data models"
 sidebarTitle: "Data models"
-description: "The data model owned by the Order Group domain."
+description: "Fields, indexes, and relations of the OrderGroup data model in the Seller module."
 ---
 
-The Order Group domain is owned by the **Seller module**. There is no separate
-order-group module. This reference lists its data model and fields. For the full
-module overview, see the [Order Group overview](/platform/order-group/overview).
+Order groups have one data model, `OrderGroup`, registered on the Seller module. There is no separate order group module: resolve it with `MercurModules.SELLER`. The model is defined in `packages/core/src/modules/seller/models/order-group.ts`, and its record type is `OrderGroupDTO` from `@mercurjs/types`.
 
 ## OrderGroup
 
-Table `order_group`, id prefix `og`. The aggregate over the per-seller orders
-created from a single cart.
+The parent record over the child orders created from one completed cart. Table `order_group`, id prefix `og`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
-| `id` | text | Primary key (prefix `og`) |
-| `display_id` | integer | Auto-incrementing, human-readable reference |
-| `customer_id` | text | Nullable; who placed the group |
-| `cart_id` | text | The originating cart (read-only link to Cart) |
-| `seller_count` | number | **Computed**: distinct sellers with a child order |
-| `total` | bigNumber | **Computed**: sum of child order totals |
-| `created_at` / `updated_at` | dateTime | Timestamps |
-| `deleted_at` | dateTime | Nullable; soft-delete marker |
-
-Relations: `orders` (one-to-many through the `order_group_order` link table),
-`cart` (read-only, via `cart_id`).
-
-<Note>
-  `seller_count` and `total` are marked `computed()`. They hold no value on the
-  row and are aggregated from the group's child orders each time it's read. See
-  [Computed totals](/platform/order-group/concepts/computed-totals).
-</Note>
-
-<Warning>
-  The `cart_id` link is **read-only**. The cart is frozen (`completed_at` is set)
-  the moment the split runs, so it's a historical reference and can't be written
-  through the group.
-</Warning>
+| `id` | `text` | Primary key with the prefix `og` |
+| `display_id` | `autoincrement` | Integer assigned by the database in creation order, for people to quote |
+| `customer_id` | `text`, nullable | Id of the customer on the completed cart, or `null` when the cart had none |
+| `cart_id` | `text` | Id of the completed cart; backs the read-only link to the Cart module |
+| `seller_count` | `number`, computed | Number of distinct sellers across the group’s child orders; not stored |
+| `total` | `bigNumber`, computed | Sum of the child orders’ `current_order_total`; not stored, returned as a `number` |
+| `created_at` | `dateTime` | Set when the record is created |
+| `updated_at` | `dateTime` | Set when the record changes |
+| `deleted_at` | `dateTime`, nullable | Soft-delete marker |
+
+The computed fields are filled by the Seller module’s `OrderGroupRepository` on every read. See [Computed totals](/platform/order-group/concepts/computed-totals).
+
+### Indexes
+
+The model declares three partial indexes, each limited to rows where `deleted_at IS NULL`:
+
+| Index | Columns | Serves |
+| --- | --- | --- |
+| `IDX_order_group_cart_id` | `cart_id` | The one-group-per-cart lookup at checkout |
+| `IDX_order_group_customer_id_created_at` | `customer_id`, `created_at` | A customer’s order history, newest first |
+| `IDX_order_group_created_at` | `created_at` | The default newest-first list |
+
+### Relations
+
+`OrderGroup` has no relations inside the Seller module. It reaches other modules through module links:
+
+| Alias | Target | Cardinality | Link |
+| --- | --- | --- | --- |
+| `orders` | `Order` (Order module) | One group to many orders | `order_group_order` |
+| `cart` | `Cart` (Cart module) | One group to one cart, read-only | `cart_id` field |
+
+See [Links](/platform/order-group/reference/links) for the definitions and `query.graph` examples.
+
+## Mutation types
+
+`@mercurjs/types` exports the input shapes for the generated create and update methods:
+
+| Type | Fields |
+| --- | --- |
+| `CreateOrderGroupDTO` | `cart_id: string`, `customer_id?: string \| null` |
+| `UpdateOrderGroupDTO` | `id: string`, `customer_id?: string`, `cart_id?: string` |
+
+Checkout creates every group through `createOrderGroupStep`. Mercur never updates a group after that.

package/content/platform/order-group/reference/events.mdx

@@ -1,22 +1,40 @@
 ---
-title: "Event reference"
+title: "Order group events"
 sidebarTitle: "Events"
-description: "Events emitted by the Order Group domain, for subscribers and side effects."
+description: "The events emitted when checkout splits a cart into an order group, with their payloads and a subscriber example."
 ---
 
-The Order Group domain emits an event when a group is created during checkout.
-Subscribe to it to run side effects such as sending an order confirmation,
-syncing external systems, or kicking off follow-up workflows, instead of polling.
+Order groups emit one event of their own, `order_group.created`, when checkout splits a cart. The same run emits Medusa’s `order.placed` for every child order. Subscribe to these events to send confirmations, sync external systems, or start follow-up workflows.
+
+## Events
+
+Both events come from `completeCartWithSplitOrdersWorkflow`. Neither is emitted when the workflow returns an existing group for a cart that was already split.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `order_group.created` | Checkout creates a group for a completed cart | `{ id }`, the group id |
+| `order.placed` | Checkout creates a child order, once per seller | `{ id }`, the order id |
+
+The event name is available as `OrderGroupWorkflowEvents.CREATED` from `@mercurjs/core/workflows`. `order.placed` is Medusa’s `OrderWorkflowEvents.PLACED` from `@medusajs/framework/utils`.
+
+## Subscribe to a new group
+
+Use `order_group.created` for work that concerns the whole purchase, such as one confirmation email for a checkout that spans three sellers:
 
 ```ts title="src/subscribers/order-group-created.ts"
 import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { getOrderGroupDetailWorkflow } from "@mercurjs/core/workflows"
 
 export default async function orderGroupCreatedHandler({
   event,
   container,
 }: SubscriberArgs<{ id: string }>) {
-  const orderGroupId = event.data.id
-  // ...send a confirmation, notify sellers, etc.
+  const { result: group } = await getOrderGroupDetailWorkflow(container).run({
+    input: {
+      order_group_id: event.data.id,
+      fields: ["id", "display_id", "total", "orders.seller.name"],
+    },
+  })
 }
 
 export const config: SubscriberConfig = {
@@ -24,14 +42,8 @@ export const config: SubscriberConfig = {
 }
 ```
 
-## Order group events
-
-| Event | Emitted when | Payload |
-| --- | --- | --- |
-| `order_group.created` | A cart is split and its parent group is created | `{ id }` |
+The subscriber loads the new group with its child orders and sellers, ready to pass to your notification provider.
 
-<Note>
-  The same checkout split also emits `order.placed` for each child order created.
-  Subscribe to `order.placed` when you need to react per seller order, and to
-  `order_group.created` when you need the purchase as a whole.
-</Note>
+<Tip>
+  Subscribe to `order.placed` instead when the work belongs to one seller, such as notifying that seller of a new order. Each child order fires its own event.
+</Tip>

package/content/platform/order-group/reference/links.mdx

@@ -1,45 +1,106 @@
 ---
-title: "Links to other modules"
+title: "Order group links"
 sidebarTitle: "Links"
-description: "How the Order Group domain links to carts, orders, sellers, and offers."
+description: "The module links that connect an order group to its cart and child orders, and its orders to sellers and offers."
 ---
 
-Modules in Mercur never reference each other directly. They connect through
-**module links**. The `OrderGroup` entity (owned by the Seller module) sits at
-the center of a completed multi-seller purchase, linking the cart it came from to
-the per-seller orders it produced. Once a link is defined, you retrieve related
-records with `query.graph` using the link alias.
+Mercur modules never reference each other directly, so an order group reaches carts and orders through module links. Two links start at the group. Two more, on the child orders, connect each order to its seller and each order line item to its offer. All four are defined in `packages/core/src/links/`, and checkout creates their rows when it splits a cart.
+
+## Order group to order
+
+Connects a group to its child orders, one per seller.
+
+| | |
+| --- | --- |
+| **Sides** | `OrderGroup` (Seller module) and `Order` (Order module) |
+| **Cardinality** | One group to many orders |
+| **Table** | `order_group_order` |
+| **Defined in** | `order-group-order-link.ts` |
 
 ```ts
-const { data: groups } = await query.graph({
+const { data: [group] } = await query.graph({
   entity: "order_group",
-  fields: ["id", "display_id", "cart.id", "orders.id", "orders.total"],
+  fields: ["id", "display_id", "orders.id", "orders.total"],
+  filters: { id: "og_01JD8Q1234567" },
+})
+```
+
+To go from an order to its group, query the link entity directly:
+
+```ts
+const { data: [row] } = await query.graph({
+  entity: "order_group_order",
+  fields: ["order_group_id"],
+  filters: { order_id: "order_01JD8Q1234568" },
 })
 ```
 
-## Group links
+## Order group to cart
 
-| Linked module | Relationship |
+Exposes the completed cart a group was created from. The link is read-only: it reads the group’s `cart_id` column and has no table of its own.
+
+| | |
 | --- | --- |
-| **Cart** | A group references the one cart it was created from (`order_group.cart_id`, **read-only**). Carts are immutable after checkout. |
-| **Order** | A group has many child orders, one per seller, through the `order_group_order` table. |
+| **Sides** | `OrderGroup.cart_id` (Seller module) and `Cart` (Cart module) |
+| **Cardinality** | One group to one cart |
+| **Table** | None, `readOnly: true` |
+| **Defined in** | `order-group-cart-link.ts` |
 
-## Order links
+```ts
+const { data: [group] } = await query.graph({
+  entity: "order_group",
+  fields: ["id", "cart.id", "cart.email", "cart.completed_at"],
+  filters: { id: "og_01JD8Q1234567" },
+})
+```
 
-The child orders produced by the split carry their own marketplace links:
+You can’t create or dismiss this link with `link.create` or `link.dismiss`. It changes only if `cart_id` changes, and Mercur never updates it.
 
-| Linked module | Relationship |
+## Order to seller
+
+Connects each child order to the seller who fulfills it.
+
+| | |
 | --- | --- |
-| **Seller** | Each order belongs to one seller (`order_order_seller_seller`); a seller has many orders. |
-| **Offer** | Each order line item links to the offer it was purchased from (`order_line_item` → `offer`, list on the line-item side so one offer can back many order lines). |
-
-<Note>
-  The `cart_id` link is resolved from the field on the group and can't be written
-  through the link itself. The split sets it once, at creation.
-</Note>
-
-<Tip>
-  To scope a group to a single seller, filter its child orders by
-  `orders.seller.id`. The list workflow does exactly this when you pass a
-  `sellerId`. See [List order groups](/platform/order-group/guides/list-order-groups).
-</Tip>
+| **Sides** | `Order` (Order module) and `Seller` (Seller module) |
+| **Cardinality** | Many orders to one seller |
+| **Link entity** | `order_seller` |
+| **Defined in** | `order-seller-link.ts` |
+
+```ts
+const { data: [group] } = await query.graph({
+  entity: "order_group",
+  fields: ["id", "orders.id", "orders.seller.id", "orders.seller.name"],
+  filters: { id: "og_01JD8Q1234567" },
+})
+```
+
+`getOrderGroupsListWorkflow` reads `orders.seller.id` to trim each group to one seller when you pass `sellerId`.
+
+## Order line item to offer
+
+Records which offer each order line item was bought from. Checkout copies it from the matching cart line item’s offer link.
+
+| | |
+| --- | --- |
+| **Sides** | `OrderLineItem` (Order module) and `Offer` (Offer module) |
+| **Cardinality** | Many order line items to one offer |
+| **Defined in** | `order-line-item-offer-link.ts` |
+
+```ts
+const { data: [group] } = await query.graph({
+  entity: "order_group",
+  fields: ["id", "orders.items.id", "orders.items.offer.id"],
+  filters: { id: "og_01JD8Q1234567" },
+})
+```
+
+The line item side is a list, so one offer can back line items in any number of orders and groups.
+
+## Links checkout creates for each order
+
+Besides the links above, `completeCartWithSplitOrdersWorkflow` creates these rows for every child order:
+
+- **Order to cart**: Medusa’s own link from each child order to the completed cart
+- **Order to promotion**: for each promotion owned by the order’s seller
+- **Seller to customer**: when the customer hasn’t bought from that seller before