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
A single payment collection is shared across all of a cart’s split orders and stays on the cart, not on each order. Split orders are not linked directly to the payment collection (Medusa’s order ↔ payment_collection link is one-to-one on the payment-collection side). Read the payment collection through the cart:
Order-group and vendor order reads normalize cart.payment_collection back onto payment_collections and recompute payment_status from it, so consumers keep the familiar shape. When requesting fields on vendor order routes, make sure the request does not replace route defaults that already include cart.payment_collection.* (a fields= list containing bare fields replaces defaults in Medusa; use +-prefixed fields to merge, or include the cart.payment_collection.* paths explicitly).

​
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.