An order group is a container created during checkout when a customer buys from multiple sellers. It groups the individual per-seller orders that originate from a single cart, giving customers and admins a unified view of what was purchased.Documentation Index
Fetch the complete documentation index at: https://docs.mercurjs.com/llms.txt
Use this file to discover all available pages before exploring further.
Data model
| Field | Type | Description |
|---|---|---|
id | text | Unique identifier (prefix og_) |
display_id | serial | Auto-incrementing human-readable ID |
customer_id | text | The customer who placed the order (nullable) |
cart_id | text | The cart this order group originated from |
seller_count | number | Number of distinct sellers in the group (computed) |
total | bigNumber | Sum of all order totals in the group (computed) |
seller_count and total are computed fields — they are calculated from linked orders at query time, not stored as columns. seller_count is the count of distinct sellers across all orders in the group, and total is the sum of each order’s current_order_total from the order summary.Relationships
Order groups connect to other entities through two links:Cart (read-only)
Links the order group back to its originating cart via thecart_id field. This is a read-only link — carts are immutable after checkout.
Orders (one-to-many)
Links the order group to multiple orders through a join tableorder_group_order. Each order in the group belongs to a different seller.
How order groups are created
Order groups are created automatically during checkout by thecompleteCartWithSplitOrdersWorkflow. This is what happens when a customer completes a cart containing products from multiple sellers:
- Lock — The workflow acquires a lock on the cart to prevent double-processing
- Group by seller — Cart items are grouped by seller (via the product-seller link)
- Create orders — A separate Medusa order is created for each seller, containing only that seller’s items and shipping
- Create order group — An order group is created with the customer and cart references
- Link everything — The workflow creates links between:
- Each order and the order group
- Each order and its seller
- Each order and the cart’s payment collection
- Each seller and the customer (if new relationship)
- Finalize — Inventory is reserved, payment is authorized, and the
order_group.createdevent is emitted
Payment collections are linked at the individual order level, not on the order group. This is a deliberate design decision — each per-seller order gets its own link to the payment collection, which enables per-order capture and refund flows.
Events
| Event | Payload | When |
|---|---|---|
order_group.created | { id: string } | After checkout creates a new order group |
API endpoints
List order groups (Admin)
customer_id, seller_id, status, sales_channel_id, and created_at. Paginated with offset and limit (default 50).
Get order group detail (Admin)
List order groups (Store)
Get order group detail (Store)
404 if the order group doesn’t belong to the authenticated customer.
Workflows
| Workflow | Purpose |
|---|---|
getOrderGroupsListWorkflow | Retrieves a paginated list of order groups with aggregated payment and fulfillment statuses for each |
getOrderGroupDetailWorkflow | Retrieves a single order group with full order details and aggregated statuses |
createOrderGroupStep | Internal step used by completeCartWithSplitOrdersWorkflow — not called directly |
payment_status and fulfillment_status for each order group by aggregating across all linked orders.