Skip to main content
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.

​
Data model

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 the cart_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 table order_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 the completeCartWithSplitOrdersWorkflow. This is what happens when a customer completes a cart containing products from multiple sellers:
  1. Lock — The workflow acquires a lock on the cart to prevent double-processing
  2. Group by seller — Cart items are grouped by seller (via the product-seller link)
  3. Create orders — A separate Medusa order is created for each seller, containing only that seller’s items and shipping
  4. Create order group — An order group is created with the customer and cart references
  5. Link everything — The workflow creates links between:
    • Each order and the order group
    • Each order and its seller
    • Each seller and the customer (if new relationship)
  6. Finalize — Inventory is reserved, payment is authorized, and the order_group.created event is emitted

​
Payments

The customer pays for the cart once: one payment collection on the cart, one payment at the payment provider. Medusa links a payment collection to a single order, so the orders of a cart share that payment through the cart until it is captured:
When the cart payment is captured, it is split. Every order gets a payment collection of its own, linked to the order, with a captured payment for the order’s share. That payment is on the same provider as the cart payment and points at the same charge. Shares are proportional to the order totals, rounded to the currency precision, and sum exactly to the captured amount.
From then on Medusa’s order and payment workflows and the stock admin and vendor routes work on the order unchanged. Order reads expose whichever applies under payment_collections: the cart’s collection before the capture, the order’s own afterwards.
The split, and voiding the authorization after the last cancel, run in subscribers to payment.captured and order.canceled, shortly after the request returns. A provider that captures on authorization is split during checkout.
Orders whose payment was captured before this model was introduced are not split retroactively and keep the cart’s shared collection.

​
Events

​
API endpoints

​
List order groups (Admin)

Supports filtering by customer_id, seller_id, status, sales_channel_id, and created_at. Paginated with offset and limit (default 50).

​
Get order group detail (Admin)

Returns the order group with aggregated payment and fulfillment statuses across all orders.

​
List order groups (Store)

Returns only order groups belonging to the authenticated customer. Includes nested order data with items, variants, products, and seller information.

​
Get order group detail (Store)

Returns a single order group. Throws 404 if the order group doesn’t belong to the authenticated customer.

​
Workflows

The list and detail workflows automatically inject order-related fields (items, payment collections, fulfillments) and compute an overall payment_status and fulfillment_status for each order group by aggregating across all linked orders.