Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

5.1 KB
Raw Blame
---
title: "Order groups"
sidebarTitle: "Overview"
description: "Turn a cart with items from several sellers into per-seller orders under one group the shopper can track."
---

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.

<img className="block dark:hidden" src="/images/figures/order-group-overview-light.svg" alt="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." />
<img className="hidden dark:block" src="/images/figures/order-group-overview-dark.svg" alt="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." />

<Note>
  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`.
</Note>

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

<CardGroup cols={2}>
  <Card title="The order group" icon="layer-group" href="/platform/order-group/concepts/the-order-group">
    The record over a multi-seller purchase, its `display_id`, and the cart link.
  </Card>
  <Card title="Order splitting" icon="scissors" href="/platform/order-group/concepts/order-splitting">
    How checkout turns one cart into one order per seller.
  </Card>
  <Card title="Computed totals" icon="calculator" href="/platform/order-group/concepts/computed-totals">
    Where `seller_count`, `total`, and child order statuses come from.
  </Card>
</CardGroup>

## Examples

Build against order groups in your own server code.

<CardGroup cols={2}>
  <Card title="Retrieve an order group" icon="magnifying-glass" href="/platform/order-group/guides/retrieve-an-order-group">
    Load one group with its child orders and their statuses.
  </Card>
  <Card title="List order groups" icon="list" href="/platform/order-group/guides/list-order-groups">
    Filter, page, and scope groups to a seller.
  </Card>
  <Card title="Split a cart" icon="scissors" href="/platform/order-group/guides/split-a-cart">
    Complete a cart into a group and hook into the split.
  </Card>
</CardGroup>

## Resources

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

<CardGroup cols={2}>
  <Card title="Data models" icon="table" href="/platform/order-group/reference/data-models">
    The `OrderGroup` model, its fields, and indexes.
  </Card>
  <Card title="Links" icon="link" href="/platform/order-group/reference/links">
    How a group connects to its cart, orders, sellers, and offers.
  </Card>
  <Card title="Workflows" icon="diagram-project" href="/platform/order-group/reference/workflows">
    The checkout split, the read workflows, and their hooks.
  </Card>
  <Card title="Service" icon="gear" href="/platform/order-group/reference/service">
    Seller module methods for order group records.
  </Card>
  <Card title="Events" icon="bell" href="/platform/order-group/reference/events">
    The events emitted when a cart splits into a group.
  </Card>
</CardGroup>