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

package/content/platform/order-group/concepts/computed-totals.mdx

@@ -1,59 +1,62 @@
 ---
-title: "Computed totals"
+title: "How order group totals are computed"
 sidebarTitle: "Computed totals"
-description: "Why an order group's seller count and total are derived at query time, not stored."
+description: "Why seller_count and total are summed from the child orders at read time, and how child order statuses are derived."
 ---
 
-This page covers how an order group's `seller_count` and `total` are calculated
-and why they aren't persisted.
+An order group never stores its own total. The `seller_count` and `total` fields are computed from the child orders each time you read the group, and the read workflows derive each child order’s payment and fulfillment status the same way. This keeps the group in step with its orders after edits, returns, and refunds, with no denormalized column to keep in sync.
 
-## Computed, not stored
+## Computed fields hold no value
 
-Two fields on the `OrderGroup` model are marked `computed()`. They never hold a
-value in the `order_group` row.
+Both fields are declared with `.computed()` on the model, so the `order_group` table has no column for them:
 
 ```ts
-const OrderGroup = model.define("order_group", {
-  // ...
-  seller_count: model.number().computed(),
-  total: model.bigNumber().computed(),
-})
+seller_count: model.number().computed(),
+total: model.bigNumber().computed(),
 ```
 
-`seller_count` is the number of distinct sellers with a child order in the group.
-`total` is the sum of those child orders' current totals. Both are resolved
-by aggregating across the group's linked orders each time the group is read,
-rather than being written once at creation.
+You can’t write them through `createOrderGroups` or `updateOrderGroups`. They only exist on the records the Seller module reads back.
 
-<Note>
-  Storing these values would immediately go stale: child orders can be refunded,
-  returned, or canceled after the group is created, changing both the total and,
-  effectively, the active seller set.
-</Note>
+## How the Seller module fills them
 
-## How they're aggregated
+The Seller module reads groups through a custom `OrderGroupRepository`. Its query joins each group to its child orders and sums them:
 
-When you read a group, the Seller module's order-group repository joins the group
-to its child orders (and each order to its seller and order summary) and folds
-them up:
+- **`seller_count`**: the number of distinct sellers linked to the group’s orders through `order_order_seller_seller`
+- **`total`**: the sum of `current_order_total` from each order’s summary at its current version, or `0` for a group with no orders
 
-- `seller_count`: a distinct count of the linked sellers
-- `total`: the sum of each child order's current order total
+Every list, count, and retrieve call on order groups runs through this repository, including `query.graph` on the `order_group` entity. Deleted orders and deleted links are left out.
 
 ```ts
-const orderGroup = await sellerModuleService.retrieveOrderGroup("og_123")
-// orderGroup.seller_count -> e.g. 3
-// orderGroup.total        -> e.g. 24900 (sum across child orders)
+const sellerModuleService = container.resolve(MercurModules.SELLER)
+
+const group = await sellerModuleService.retrieveOrderGroup(
+  "og_01JD8Q1234567"
+)
 ```
 
+For a group with a 47.00 order from ACME and a 40.00 order from GLOBEX, `group.seller_count` is `2` and `group.total` is `87`. The repository converts `total` to a JavaScript `number`, which matches the `OrderGroupDTO` type.
+
+## Filters pick groups, not orders
+
+Order-level filters such as `seller_id`, `status`, `payment_status`, and `sales_channel_id` decide which groups match. They don’t trim the sums. A group that matches `seller_id: "sel_01JD8Q1234567"` still reports the `seller_count` and `total` of every order in it.
+
 <Tip>
-  Because `total` is a `bigNumber`, group totals stay precise no matter how many
-  child orders and currencies contribute to the aggregate.
+  To show one seller’s share of a group, read the group’s `orders` and sum the ones that belong to that seller. The list workflow’s `sellerId` input trims `orders` for you.
 </Tip>
 
-## Aggregated child statuses
+## Child order statuses
+
+`getOrderGroupDetailWorkflow` and `getOrderGroupsListWorkflow` set `payment_status` and `fulfillment_status` on every child order they return. Medusa’s `Order` model doesn’t store these, so the workflows compute them from the order’s data:
+
+| Status | Derived from | Possible values |
+| --- | --- | --- |
+| `payment_status` | The order’s payment collections: its own once the payment is split, the cart’s shared one before | `not_paid`, `awaiting`, `authorized`, `partially_authorized`, `captured`, `partially_captured`, `refunded`, `partially_refunded`, `canceled`, `requires_action` |
+| `fulfillment_status` | The `packed_at`, `shipped_at`, `delivered_at`, and `canceled_at` timestamps of its fulfillments, plus unfulfilled item quantities | `not_fulfilled`, `fulfilled`, `partially_fulfilled`, `shipped`, `partially_shipped`, `delivered`, `partially_delivered`, `canceled` |
+
+The group has no status of its own. Read the child statuses to show where each seller’s part of the purchase stands.
+
+## Related
 
-The retrieve and list workflows layer the same idea onto child orders. They
-derive each order's `payment_status` and `fulfillment_status` from its payment
-collections and fulfillments at read time, so the group reflects the live state
-of every seller's slice without any denormalized status column.
+- [Retrieve a group with its child order statuses](/platform/order-group/guides/retrieve-an-order-group)
+- [Filters the repository understands](/platform/order-group/reference/service#filters-and-sorting)
+- [The `OrderGroup` fields](/platform/order-group/reference/data-models)

package/content/platform/order-group/concepts/order-splitting.mdx

@@ -1,61 +1,63 @@
 ---
-title: "Order splitting"
+title: "How checkout splits a cart into orders"
 sidebarTitle: "Order splitting"
-description: "How a multi-seller cart becomes a group of independent per-seller orders."
+description: "How completeCartWithSplitOrdersWorkflow turns one multi-seller cart into one order per seller under a group."
 ---
 
-This page covers how a single cart spanning multiple sellers is split into
-per-seller orders at checkout.
+Order splitting is what happens when a shopper completes a cart that holds offers from several sellers. Mercur replaces Medusa’s single-order checkout with `completeCartWithSplitOrdersWorkflow`, which creates one order per seller and wraps them in an order group. Understanding the split tells you where each seller’s items, shipping, promotions, and payment end up.
 
-## Why carts are split
+## Items follow the offer’s seller
 
-A marketplace cart can hold offers from many different sellers. Each seller
-fulfills, ships, and settles independently, so a single combined order would be
-impossible to operate. Instead, on completion the cart is divided along seller
-boundaries. Every seller with items in the cart gets its own `Order`, and all of
-those orders are attached to one parent `OrderGroup`.
+The workflow groups line items by `item.offer.seller_id`. Sellers sell against a shared master catalog through offers, so the offer, not the product, ties a line item to a seller. Every seller with at least one item gets one child order.
 
-The split is driven by the `completeCartWithSplitOrdersWorkflow`. It groups the
-cart's line items by the seller behind each offer, and builds one order per
-seller from that seller's items and shipping methods.
+The split enforces two rules before it creates anything:
+
+- **Every item has a seller**: `validateSellerCartItemsStep` throws `INVALID_DATA` when any line item has no offer with a `seller_id`
+- **Every seller’s shipping is covered**: `validateSellerCartShippingStep` throws when items that require shipping have no matching shipping method
+
+Each child order gets the seller’s line items plus the shipping methods whose shipping option belongs to that seller. Addresses, email, currency, locale, region, and sales channel are copied from the cart.
+
+## Promotions stay with their seller
+
+Promotion adjustments are split by scope. A promotion linked to a seller only keeps its adjustments on that seller’s items and shipping, and the workflow links the promotion to that seller’s child order. A marketplace promotion with no seller keeps its adjustments on every order it touched, and the workflow links it to no order.
+
+## What the split creates
+
+The workflow creates everything for the group in one run:
+
+1. Create the `OrderGroup` with the cart’s `customer_id` and `cart_id`.
+2. Create one `Order` per seller, with status `pending` unless the `setOrderStatus` hook says otherwise.
+3. Link each order to the group, its seller, and the cart, and link new customers to the sellers they bought from.
+4. Mirror each cart line item’s offer link onto the new order line item.
+5. Reserve inventory for offers that manage inventory, and register promotion usage.
+6. Set `completed_at` on the cart and emit `order.placed` and `order_group.created`.
+7. Authorize the payment session, split a captured payment, and refresh commission lines per order.
 
 ```ts
 import { completeCartWithSplitOrdersWorkflow } from "@mercurjs/core/workflows"
 
 const { result } = await completeCartWithSplitOrdersWorkflow(container).run({
-  input: { cart_id: "cart_123" },
+  input: { cart_id: "cart_01JD8Q1234567" },
 })
-// result.order_group_id -> the parent group
 ```
 
-<Note>
-  Items are grouped by `item.offer.seller_id`. Sellers list against the shared
-  master catalog through **offers**, so the offer, not the product, is what
-  ties a line item to a seller.
-</Note>
+The run returns `{ order_group_id }`. Mercur’s cart completion route and its `processPaymentWorkflow` both run this workflow, so a webhook-driven checkout also produces a group.
 
-## What the split produces
+## Payment stays on the cart until capture
 
-For each seller in the cart the workflow, in one transaction:
+The child orders share the cart’s payment collection until the payment is captured. Medusa allows a payment collection to belong to one order only, so the split doesn’t link the orders to it. Once the payment is captured, `splitCapturedCartPaymentWorkflow` gives each order a payment collection of its own for its share. It runs inside checkout for providers that capture on authorization, and from the `payment.captured` subscriber for the rest.
 
-- creates a child `Order` with that seller's line items and shipping methods
-- links each order to the group (`order_group_order`) and to its seller (`order_order_seller_seller`)
-- mirrors the line-item → offer links onto the new order lines
-- splits payment captures proportionally across the child orders
-- reserves offer-scoped inventory and refreshes commission lines per order
+## One group per cart
 
-Once every child order is created, the workflow emits `order.placed` for the
-orders and `order_group.created` for the group.
+The split runs at most once per cart. The workflow takes a lock on the cart id, then looks for an existing group with the same `cart_id`. If it finds one, it skips the split and returns that group’s id, so a retried request or a duplicate webhook can’t create a second set of orders.
 
-<Tip>
-  Promotions are attributed per seller: a seller-scoped promotion links only to
-  that seller's child order, while marketplace-wide promotions are applied as
-  cart adjustments and belong to no single order.
-</Tip>
+<Warning>
+  Child orders don’t carry the cart’s credit lines yet. The split creates every order with an empty `credit_lines` list.
+</Warning>
 
-## Independent child orders
+## Related
 
-After the split, each child order lives its own life. Fulfillment, returns, and
-refunds are handled per order, so one seller can ship while another is still
-preparing, without affecting the rest of the group. The group remains the
-single reference the shopper uses to see the purchase as a whole.
+- [Run the split from your own code](/platform/order-group/guides/split-a-cart)
+- [The workflow’s input, hooks, and events](/platform/order-group/reference/workflows#completecartwithsplitordersworkflow)
+- [How offers tie items to sellers](/platform/offer/concepts/what-is-an-offer)
+- [Commission lines per order](/platform/commission/concepts/order-commission-lines)

package/content/platform/order-group/concepts/the-order-group.mdx

@@ -1,21 +1,16 @@
 ---
-title: "The order group"
+title: "What an order group is"
 sidebarTitle: "The order group"
-description: "The aggregate record over a multi-seller purchase, its display id, and cart link."
+description: "The record that ties a multi-seller purchase together: its display id, its customer, its cart, and its child orders."
 ---
 
-This page covers the order group record and how it aggregates the per-seller
-orders created from a single cart.
+An order group is the record that represents one checkout across several sellers. Sellers can’t share an order, because each one ships, refunds, and gets paid on their own, so Mercur gives every seller a child order and keeps the purchase together in a group. You use the group whenever you need the shopper’s view of a purchase: an order history page, a confirmation email, or an operator’s order list.
 
-## Order group
+## The OrderGroup record
 
-An order group is the shopper-facing wrapper over a multi-seller purchase. It is
-represented by the `OrderGroup` data model (table `order_group`, id prefix
-`og`). When a cart containing offers from more than one seller is completed, the
-cart is split into one child order per seller. All of those orders are attached
-to a single group.
+The group is the `OrderGroup` data model in the Seller module, stored in the `order_group` table with the id prefix `og`. It holds four stored fields and two computed ones:
 
-```ts
+```ts title="packages/core/src/modules/seller/models/order-group.ts"
 const OrderGroup = model.define("order_group", {
   id: model.id({ prefix: "og" }).primaryKey(),
   display_id: model.autoincrement(),
@@ -26,39 +21,51 @@ const OrderGroup = model.define("order_group", {
 })
 ```
 
-The group carries a human-readable `display_id`, an auto-incrementing integer,
-so shoppers and operators can reference the purchase without exposing the
-internal id. `customer_id` records who placed it. `seller_count` and `total`
-are computed at read time. See [Computed totals](/platform/order-group/concepts/computed-totals).
+Each field has one job:
+
+- **`display_id`**: an auto-incrementing integer, so people can quote a purchase without the internal id
+- **`customer_id`**: the customer who completed the cart, or `null` when the cart has no customer
+- **`cart_id`**: the cart the group was created from
+- **`seller_count` and `total`**: summed from the child orders when you read the group, covered in [Computed totals](/platform/order-group/concepts/computed-totals)
 
 <Note>
-  A group is created even for a single-seller cart, so every completed
-  marketplace order has exactly one parent group regardless of how many sellers
-  it spans.
+  Checkout creates a group for every completed cart, even when the cart has items from one seller. Every marketplace order therefore has exactly one parent group.
 </Note>
 
 ## The cart link
 
-Each group holds a `cart_id` pointing back to the cart it was created from. This
-is exposed as a **read-only** link to the Cart module. The cart is frozen
-(`completed_at` is set) the moment the split runs, so the reference is a
-historical record, not something you write through.
+The `cart_id` field backs a read-only link to Medusa’s Cart module, so you can expand `cart.*` from a group. Checkout sets `completed_at` on the cart in the same run that creates the group, and the cart doesn’t change after that. Treat `cart_id` as a stable pointer to the basket the shopper paid for.
 
 ```ts
-const { data: groups } = await query.graph({
+const { data: [group] } = await query.graph({
   entity: "order_group",
-  fields: ["id", "display_id", "cart.id", "orders.id"],
+  fields: ["id", "display_id", "cart.id", "cart.email"],
+  filters: { id: "og_01JD8Q1234567" },
 })
 ```
 
-<Tip>
-  Because the cart is immutable after checkout, the `cart_id` is safe to treat as
-  a stable audit pointer to the exact basket the shopper paid for.
-</Tip>
+The query loads one group and the cart it came from. Because the link is read-only, you can’t create or dismiss it with `link.create`: it always follows the `cart_id` column.
 
 ## Child orders
 
-The group doesn't store line items itself. Those live on the child `Order`
-records, linked through the `order_group_order` table. Loading a group's
-`orders.*` gives you each seller's slice, each with its own fulfillment, payment,
-returns, and refunds.
+A group holds no line items. The items live on the child `Order` records, one per seller, connected through the `order_group_order` link table. Each child order is a regular Medusa order with its own items, shipping methods, fulfillments, returns, and refunds:
+
+- **Seller**: each child order links to the seller who fulfills it
+- **Line items**: each order line item links to the offer it was bought from
+- **Cart**: each child order also links back to the completed cart
+
+```ts
+const { data: [group] } = await query.graph({
+  entity: "order_group",
+  fields: ["id", "orders.id", "orders.seller.name", "orders.status"],
+  filters: { id: "og_01JD8Q1234567" },
+})
+```
+
+The query returns the group with each child order and the seller behind it. To go from an order to its group, query the `order_group_order` link entity by `order_id`.
+
+## Related
+
+- [How checkout splits a cart into child orders](/platform/order-group/concepts/order-splitting)
+- [How `seller_count` and `total` are computed](/platform/order-group/concepts/computed-totals)
+- [Every link around an order group](/platform/order-group/reference/links)

package/content/platform/order-group/guides/list-order-groups.mdx

@@ -1,71 +1,111 @@
 ---
-title: "List order groups"
+title: "List and filter order groups"
 sidebarTitle: "List order groups"
-description: "Page through order groups and scope them to a seller with getOrderGroupsListWorkflow."
+description: "Page through order groups, filter them, and scope them to one seller with getOrderGroupsListWorkflow."
 ---
 
-In this guide, you'll learn how to list order groups from server code, page
-through the results, and optionally scope them to a single seller.
-
-Mercur exposes a `getOrderGroupsListWorkflow` that returns groups with their
-aggregated child orders and a total count for pagination.
-
-## Run the workflow
-
-```ts title="src/api/custom/order-groups/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { getOrderGroupsListWorkflow } from "@mercurjs/core/workflows"
-
-export async function GET(req: MedusaRequest, res: MedusaResponse) {
-  const { result } = await getOrderGroupsListWorkflow(req.scope).run({
-    input: {
-      fields: ["id", "display_id", "total", "seller_count"],
-      variables: {
-        skip: 0,
-        take: 20,
-        order: { created_at: "DESC" },
-      },
-    },
-  })
-
-  res.json({
-    order_groups: result.rows,
-    count: result.metadata?.count ?? 0,
-  })
-}
-```
+List order groups from server code when you build an order history, a report, or a seller-facing view of purchases.
 
-The workflow returns `{ rows, metadata }`, where `metadata` carries the `count`,
-`skip`, and `take` you need to drive pagination.
+## List groups in an API route
 
-<Note>
-  Filters go inside `variables`: the group repository understands `id`,
-  `customer_id`, `seller_id`, `status`, `sales_channel_id`, `created_at`,
-  `updated_at`, and a free-text `q` (matched against group id and customer id).
-  Order-level filters (`seller_id`, `status`, `sales_channel_id`) only decide
-  which groups match. A matching group's `seller_count` and `total` still
-  describe every order in the group, as covered in
-  [Computed totals](/platform/order-group/concepts/computed-totals).
-</Note>
+<Steps>
+  <Step title="Run the list workflow">
+    Pass the fields you want and put filters and pagination in `variables`.
+
+    ```ts title="src/api/admin/purchases/route.ts"
+    import type {
+      MedusaRequest,
+      MedusaResponse,
+    } from "@medusajs/framework/http"
+    import { getOrderGroupsListWorkflow } from "@mercurjs/core/workflows"
+
+    export async function GET(req: MedusaRequest, res: MedusaResponse) {
+      const { result } = await getOrderGroupsListWorkflow(req.scope).run({
+        input: {
+          fields: ["id", "display_id", "total", "seller_count"],
+          variables: { skip: 0, take: 20, order: { display_id: "DESC" } },
+        },
+      })
+
+      res.json({
+        order_groups: result.rows,
+        count: result.metadata?.count ?? 0,
+      })
+    }
+    ```
+
+    The workflow returns `{ rows, metadata }`. `metadata` carries `count`, `skip`, and `take` for pagination. Every row includes its child `orders` with `payment_status` and `fulfillment_status`.
+  </Step>
+  <Step title="Add filters">
+    Put filter keys next to the pagination keys in `variables`:
+
+    ```ts
+    variables: {
+      customer_id: "cus_01JD8Q1234567",
+      payment_status: ["captured", "partially_captured"],
+      created_at: { $gte: "2026-10-01T00:00:00Z" },
+      take: 20,
+    }
+    ```
+
+    This returns the customer’s groups from October 2026 that have at least one captured or partially captured child order.
+  </Step>
+</Steps>
+
+## Filters you can use
+
+The Seller module reads groups through a custom repository that understands a fixed set of top-level keys:
+
+- **Group filters**: `id`, `customer_id`, `cart_id`, as a string or an array
+- **Order filters**: `seller_id`, `status`, `payment_status`, `sales_channel_id`, which match a group when at least one child order matches
+- **Dates**: `created_at` and `updated_at`, with `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$nin`, `$like`, `$ilike`
+- **Search**: `q`, which matches the group id or customer id, and a display id such as `#G98`, `G98`, or `98` on the group or a child order
+
+You can sort by `display_id`, `created_at`, or `updated_at`. Without an `order`, groups come back newest first.
+
+<Warning>
+  The repository ignores keys it doesn’t know, including `$and` and `$or`. Pass `id` as a plain string or array, not `{ $in: [...] }`. If you need two id constraints, intersect them yourself before you call the workflow.
+</Warning>
 
-## Scope to a seller
+## Scope groups to one seller
 
-Pass a `sellerId` to get a vendor's slice. The workflow filters each group's
-child orders down to that seller, so vendors only ever see their own orders
-within a group.
+To show a seller only their part of each purchase, filter the groups and trim their orders:
 
 ```ts
-await getOrderGroupsListWorkflow(req.scope).run({
+const sellerId = "sel_01JD8Q1234567"
+
+const { result } = await getOrderGroupsListWorkflow(req.scope).run({
   input: {
-    fields: ["id", "display_id"],
-    variables: { seller_id: "sel_123", take: 20 },
-    sellerId: "sel_123",
+    fields: ["id", "display_id", "orders.total"],
+    variables: { seller_id: sellerId, take: 20 },
+    sellerId,
   },
 })
 ```
 
-<Tip>
-  Admin surfaces call this workflow with no `sellerId` for platform-wide
-  visibility. Vendor surfaces pass the resolved seller so both the query and the
-  returned child orders stay scoped to that store.
-</Tip>
+The two inputs do different jobs. `variables.seller_id` keeps only the groups where the seller has an order. `sellerId` removes the other sellers’ orders from each returned group. `sellerId` also accepts an array of seller ids.
+
+<Note>
+  `seller_count` and `total` still describe the whole group when you scope it. Sum the trimmed `orders` to get the seller’s share.
+</Note>
+
+## List groups without child orders
+
+When you only need group rows, call the Seller module service. It skips the child order expansion and the status work:
+
+```ts
+const sellerModuleService = req.scope.resolve(MercurModules.SELLER)
+
+const [groups, count] = await sellerModuleService.listAndCountOrderGroups(
+  { customer_id: "cus_01JD8Q1234567" },
+  { take: 20, order: { created_at: "DESC" } }
+)
+```
+
+`MercurModules` comes from `@mercurjs/types`. The rows still include the computed `seller_count` and `total`.
+
+## Next steps
+
+- [Retrieve one group with its child orders](/platform/order-group/guides/retrieve-an-order-group)
+- [Why filters don’t change the totals](/platform/order-group/concepts/computed-totals#filters-pick-groups-not-orders)
+- [`getOrderGroupsListWorkflow` reference](/platform/order-group/reference/workflows#getordergroupslistworkflow)

package/content/platform/order-group/guides/retrieve-an-order-group.mdx

@@ -1,63 +1,114 @@
 ---
-title: "Retrieve an order group"
+title: "Retrieve an order group with its child orders"
 sidebarTitle: "Retrieve an order group"
-description: "Load an order group and its aggregated child orders with getOrderGroupDetailWorkflow."
+description: "Load one order group, its child orders, and their payment and fulfillment status with getOrderGroupDetailWorkflow."
 ---
 
-In this guide, you'll learn how to load a single order group together with its
-child orders from your own server code.
+Load one order group from server code when you build an order page, an email, or an export that needs the whole purchase.
 
-Mercur exposes a `getOrderGroupDetailWorkflow` that fetches the group, expands
-its child orders, and derives each order's payment and fulfillment status. 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/order-group/[id]/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { getOrderGroupDetailWorkflow } from "@mercurjs/core/workflows"
+- **A completed multi-seller cart**: at least one order group in your database, for example from a storefront checkout
+- **The group id**: an id with the `og` prefix, such as `og_01JD8Q1234567`
 
-export async function GET(req: MedusaRequest, res: MedusaResponse) {
-  const { result: order_group } = await getOrderGroupDetailWorkflow(
-    req.scope
-  ).run({
-    input: {
-      order_group_id: req.params.id,
-      fields: ["id", "display_id", "total", "seller_count", "cart_id"],
-    },
-  })
+## Load the group in an API route
 
-  res.json({ order_group })
-}
-```
+<Steps>
+  <Step title="Create the route">
+    Run `getOrderGroupDetailWorkflow` with the group id and the fields you want back.
+
+    ```ts title="src/api/admin/purchases/[id]/route.ts"
+    import type {
+      MedusaRequest,
+      MedusaResponse,
+    } from "@medusajs/framework/http"
+    import { getOrderGroupDetailWorkflow } from "@mercurjs/core/workflows"
+
+    export async function GET(req: MedusaRequest, res: MedusaResponse) {
+      const { result: order_group } = await getOrderGroupDetailWorkflow(
+        req.scope
+      ).run({
+        input: {
+          order_group_id: req.params.id,
+          fields: ["id", "display_id", "total", "seller_count", "cart_id"],
+        },
+      })
+
+      res.json({ order_group })
+    }
+    ```
+
+    The workflow adds the child order fields it needs on top of yours, so `order_group.orders` is always populated. Each order carries `payment_status` and `fulfillment_status`.
+  </Step>
+  <Step title="Add the child order fields you display">
+    Ask for extra order fields with the `orders.` prefix.
+
+    ```ts
+    const fields = [
+      "id",
+      "display_id",
+      "total",
+      "orders.display_id",
+      "orders.total",
+      "orders.seller.name",
+    ]
+    ```
 
-The workflow always expands the group's child orders regardless of the `fields`
-you pass, so `order_group.orders` is populated with each seller's slice.
+    The workflow always returns `orders.id`, `orders.status`, `orders.currency_code`, and `orders.items.*`. Everything else on the order comes from your list.
+  </Step>
+  <Step title="Handle a missing group">
+    The workflow throws a `NOT_FOUND` error when no group has the id. Inside an API route, Medusa’s error handler turns it into a 404 response, so you don’t need to check the result.
+  </Step>
+</Steps>
+
+## Keep payment collections and fulfillments in the response
+
+The workflow loads every child order’s payment collections and fulfillments to compute the statuses, then drops them from the result. To keep them, include a field that contains `payment_collections` or `fulfillments`:
+
+```ts
+fields: [
+  "id",
+  "orders.payment_collections.id",
+  "orders.fulfillments.id",
+]
+```
 
-<Note>
-  The workflow only fetches heavy relations when you ask for them: include a
-  `payment_collections` field to get per-order `payment_status`, and a
-  `fulfillments` field to get `fulfillment_status`. Otherwise those collections
-  are stripped from the response to keep it lean.
-</Note>
+Before the payment is captured, `payment_collections` holds the cart’s shared collection. After capture, it holds the order’s own collection. Fields that start with `orders.cart` keep the child orders’ `cart` in the result too.
 
 ## Follow the cart link
 
-The group's read-only `cart_id` points back to the immutable cart it came from.
-Expand it through the module link when you need the original basket:
+Expand the read-only cart link to get the basket the group came from:
 
 ```ts
-await getOrderGroupDetailWorkflow(req.scope).run({
-  input: {
-    order_group_id: req.params.id,
-    fields: ["id", "cart.id", "cart.email", "orders.id", "orders.total"],
-  },
+fields: ["id", "cart.id", "cart.email", "cart.completed_at"]
+```
+
+The cart is completed and frozen, so these values match what the shopper paid for.
+
+## Find the group for an order
+
+When you start from a child order id, look up the group through the `order_group_order` link entity, then run the workflow with its id:
+
+```ts
+const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
+
+const { data: [link] } = await query.graph({
+  entity: "order_group_order",
+  fields: ["order_group_id"],
+  filters: { order_id: "order_01JD8Q1234568" },
 })
 ```
 
+`ContainerRegistrationKeys` comes from `@medusajs/framework/utils`. `link` is `undefined` when the order isn’t part of a group.
+
 <Tip>
-  Prefer the workflow over reading the record directly. It does the child-order
-  status aggregation for you. The raw
-  [service method](/platform/order-group/reference/service) returns only the
-  group row and its computed totals.
+  Use the workflow rather than `retrieveOrderGroup` when you need child orders. The service method returns the group row and its computed totals only, without orders or statuses.
 </Tip>
+
+## Next steps
+
+- [List and filter order groups](/platform/order-group/guides/list-order-groups)
+- [How the child order statuses are derived](/platform/order-group/concepts/computed-totals#child-order-statuses)
+- [`getOrderGroupDetailWorkflow` reference](/platform/order-group/reference/workflows#getordergroupdetailworkflow)