Skip to main content
Use order groups to give the shopper one purchase while each seller gets an order of their own. A marketplace cart can hold offers from several sellers. At checkout, Mercur creates one child order per seller and wraps them in an order group. The group is the record the shopper sees as “my order”, while each seller fulfills, returns, and refunds their own child order. The group stores almost nothing itself: its seller count and total are summed from the child orders every time you read it. The order_group record og_01JD8Q1234567 in front, with display_id 98, its customer and read-only cart link, and computed seller_count 2 and total 87.00. Behind it, the order_group_order link lists the two child orders it sums: 47.00 for ACME and 40.00 for GLOBEX. The order_group record og_01JD8Q1234567 in front, with display_id 98, its customer and read-only cart link, and computed seller_count 2 and total 87.00. Behind it, the order_group_order link lists the two child orders it sums: 47.00 for ACME and 40.00 for GLOBEX.
An order group is the OrderGroup data model (id prefix og). It belongs to the Seller module, not a module of its own, so there is no ORDER_GROUP key. Resolve its service with MercurModules.SELLER.

​
Key features

Order groups cover a multi-seller purchase from checkout to the order history:
  • Split checkout: completeCartWithSplitOrdersWorkflow turns one cart into one order per seller under a single group
  • One group per cart: completing the same cart twice returns the existing group instead of splitting again
  • Readable reference: an auto-incrementing display_id that shoppers and operators can quote
  • Frozen cart link: a read-only cart_id that points at the completed cart
  • Live totals: seller_count and total are computed from the child orders at query time, never stored
  • Derived child statuses: the read workflows add payment_status and fulfillment_status to every child order
  • Seller scoping: the list workflow can trim each group down to one seller’s orders

​
How it works

A group comes to life when a cart completes:
  1. The shopper completes a cart that holds offers from ACME and GLOBEX.
  2. completeCartWithSplitOrdersWorkflow groups the line items by item.offer.seller_id.
  3. It creates one OrderGroup and one child Order per seller, then links them.
  4. It authorizes the cart’s payment and refreshes commission lines for each order.
  5. It emits order.placed for each child order and order_group.created for the group.
  6. When you read the group, the Seller module sums its child orders into seller_count and total.

​
Get started

Learn how the group, the split, and the computed totals fit together.

The order group

The record over a multi-seller purchase, its display_id, and the cart link.

Order splitting

How checkout turns one cart into one order per seller.

Computed totals

Where seller_count, total, and child order statuses come from.

​
Examples

Build against order groups in your own server code.

Retrieve an order group

Load one group with its child orders and their statuses.

List order groups

Filter, page, and scope groups to a seller.

Split a cart

Complete a cart into a group and hook into the split.

​
Resources

The data model, links, workflows, service methods, and events behind order groups.

Data models

The OrderGroup model, its fields, and indexes.

Links

How a group connects to its cart, orders, sellers, and offers.

Workflows

The checkout split, the read workflows, and their hooks.

Service

Seller module methods for order group records.

Events

The events emitted when a cart splits into a group.