The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
---
title: "Order Groups"
description: "How multi-seller checkout creates order groups — the container that ties a single cart to multiple seller orders."
---
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
| 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) |
<Info>
`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.
</Info>
## 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.
```
order_group.cart_id → cart.id
```
### 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.
```
order_group ←→ order (via order_group_order)
```
## 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:
```text
order → cart → payment_collection → payment
```
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.
```text
order → payment_collections → payment
```
From then on Medusa's order and payment workflows and the stock admin and vendor routes work on the order unchanged.
| Moment | What happens |
|--------|--------------|
| Cancel an order before capture | No payment is touched: the authorization is still needed by the cart's other orders. Once every order of the cart is canceled, the authorization is voided. |
| Capture | The cart payment is captured as a whole, by the provider webhook or from the dashboard, and split between the orders. What was charged for orders canceled earlier is refunded. |
| Refund an order's payment | The amount is refunded at the provider against the customer's charge and recorded on that order. It cannot exceed the order's share. |
| Cancel an order after capture | The order's share is refunded. |
Order reads expose whichever applies under `payment_collections`: the cart's collection before the capture, the order's own afterwards.
<Info>
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.
</Info>
<Note>
Orders whose payment was captured before this model was introduced are not split retroactively and keep the cart's shared collection.
</Note>
## Events
| Event | Payload | When |
|-------|---------|------|
| `order_group.created` | `{ id: string }` | After checkout creates a new order group |
## API endpoints
### List order groups (Admin)
```bash
curl http://localhost:9000/admin/order-groups \
-H "Authorization: Bearer <admin-token>"
```
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)
```bash
curl http://localhost:9000/admin/order-groups/<order-group-id> \
-H "Authorization: Bearer <admin-token>"
```
Returns the order group with aggregated payment and fulfillment statuses across all orders.
### List order groups (Store)
```bash
curl http://localhost:9000/store/order-groups \
-H "Authorization: Bearer <customer-token>"
```
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)
```bash
curl http://localhost:9000/store/order-groups/<order-group-id> \
-H "Authorization: Bearer <customer-token>"
```
Returns a single order group. Throws `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 |
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.