@mercurjs/docs 2.2.0-canary.40

package/content/learn/commissions.mdx

@@ -0,0 +1,175 @@
+---
+title: "Commission"
+description: "How marketplace commissions work in Mercur — rates, rules, the matching algorithm, and commission lines."
+---
+
+Commissions are how the marketplace earns revenue. Rather than storing a single commission percentage, Mercur uses a **rule-based system** where commission rates are matched to order line items based on configurable conditions, with a global default as the fallback.
+
+## Commission rates
+
+A **CommissionRate** defines how much commission the marketplace takes and when it applies.
+
+| Field | Description |
+|-------|-------------|
+| `name` | Human-readable name (e.g. "Electronics Commission") |
+| `code` | Unique system identifier |
+| `type` | `fixed` (flat amount) or `percentage` |
+| `value` | The percentage, or the flat amount used when no per-currency value matches |
+| `values` | Per-currency amounts for `fixed` rates (`currency_code` + `amount`) |
+| `include_tax` | Include tax in the base amount for calculation |
+| `include_shipping` | Whether shipping methods are also commissioned (global rate only) |
+| `is_default` | Marks the **global commission** — the fallback applied when no scoped rate matches |
+| `is_enabled` | Disabled rates are skipped entirely |
+
+<Info>
+  `percentage` rates use the scalar `value`. `fixed` rates read the per-currency `values` list and fall back to `value` when the order's currency has no entry.
+</Info>
+
+## Commission rules
+
+Rules determine **when** a rate applies. Each rule has a `reference` (the dimension) and a `reference_id` (the value to match):
+
+| Reference | Matches items whose product… |
+|-----------|------------------------------|
+| `product` | is that specific product |
+| `product_type` | has that product type |
+| `product_collection` | belongs to that collection |
+| `product_category` | belongs to that category |
+| `seller` | is sold by that seller |
+
+A rate with **no rules** matches everything — that's what makes the default rate a catch-all.
+
+### The matching algorithm
+
+For each line item:
+
+1. **Group** the rate's rules by dimension (`reference`).
+2. A rate matches when **every dimension group has at least one matching rule** — AND across dimensions, OR within a dimension. Example: a rate with rules `seller: A` and `product_category: electronics` matches only electronics sold by seller A; a rate with two `product_category` rules matches either category.
+3. Among all matching rates, the **most specific wins** — the rate scoping on the largest number of distinct dimensions.
+4. Ties break deterministically to the **oldest rate**.
+
+**Example configuration:**
+
+| Rate | Rules | Type | Value | Matches |
+|------|-------|------|-------|---------|
+| Premium seller electronics | `seller: slr_abc` + `product_category: electronics` | Percentage | 8% | Electronics from that seller (2 dimensions — most specific) |
+| Electronics commission | `product_category: electronics` | Percentage | 12% | Other sellers' electronics (1 dimension) |
+| Global commission | _(none, `is_default`)_ | Percentage | 15% | Everything else |
+
+An electronics item from seller `slr_abc` gets 8% — the two-dimension rate beats the one-dimension category rate, regardless of creation order.
+
+## The calculation pipeline
+
+The `getCommissionLines` step calculates commissions when an order is placed:
+
+1. **Load** all enabled rates with their rules and per-currency values. Rates pinned to a `currency_code` apply only to orders in that currency.
+2. **Match items** — for each line item, find matching rates and pick the most specific (see above).
+3. **Calculate** — the base amount is the item subtotal, plus tax when `include_tax` is on. Percentage: `(base × value) / 100`. Fixed: the per-currency amount.
+4. **Shipping** — governed solely by the **global commission**: when its `include_shipping` flag is on, each shipping method gets a commission line calculated from the global rate.
+5. **Output** — one `CommissionLine` per commissioned item and shipping method.
+
+<Info>
+  All commission calculations use `BigNumber` arithmetic for precision. This is critical for financial accuracy — standard floating-point math can introduce rounding errors.
+</Info>
+
+## API examples
+
+### Set up the global commission (Admin API)
+
+```bash
+curl -X POST http://localhost:9000/admin/commission-rates \
+  -H "Authorization: Bearer <admin-token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Global Commission",
+    "code": "global",
+    "type": "percentage",
+    "value": 15,
+    "is_default": true,
+    "include_shipping": true
+  }'
+```
+
+### Create a scoped rate with rules (Admin API)
+
+```bash
+curl -X POST http://localhost:9000/admin/commission-rates \
+  -H "Authorization: Bearer <admin-token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Electronics Commission",
+    "code": "electronics",
+    "type": "percentage",
+    "value": 12,
+    "rules": [
+      { "reference": "product_category", "reference_id": "pcat_electronics" }
+    ]
+  }'
+```
+
+### Create a fixed rate with per-currency amounts
+
+```bash
+curl -X POST http://localhost:9000/admin/commission-rates \
+  -H "Authorization: Bearer <admin-token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Flat Listing Fee",
+    "code": "flat-fee",
+    "type": "fixed",
+    "value": 2,
+    "values": [
+      { "currency_code": "usd", "amount": 2 },
+      { "currency_code": "eur", "amount": 1.8 }
+    ],
+    "rules": [
+      { "reference": "seller", "reference_id": "slr_abc123" }
+    ]
+  }'
+```
+
+### List commission rates
+
+```bash
+curl http://localhost:9000/admin/commission-rates \
+  -H "Authorization: Bearer <admin-token>"
+```
+
+## Commission lines
+
+A **CommissionLine** is the calculated commission for a single line item or shipping method:
+
+| Field | Description |
+|-------|-------------|
+| `item_id` | The order line item (null for shipping lines) |
+| `shipping_method_id` | The shipping method (null for item lines) |
+| `commission_rate_id` | The rate that was applied |
+| `code` | Code of the applied rate |
+| `rate` | The rate value used |
+| `amount` | The calculated commission amount |
+
+Commission lines are linked to order line items via a **read-only link**, so an order's items can be queried together with their commission data in a single request.
+
+## How commission connects to payouts
+
+Commission lines are the bridge between orders and seller earnings:
+
+1. An order is completed → commission lines are calculated for each item
+2. When the order is credited to the seller's payout account, the total commission is subtracted:
+   ```
+   seller_earnings = order.total - sum(commission_line.amount)
+   ```
+3. The marketplace retains the commission amount
+
+This separation means commission rates can be changed at any time without affecting already-calculated orders — the `CommissionLine` records serve as a permanent audit trail.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Payouts" href="/rc/learn/payouts">
+    How seller earnings settle after commission.
+  </Card>
+  <Card title="Order Groups" href="/rc/learn/order-groups">
+    The per-seller orders commissions are calculated on.
+  </Card>
+</CardGroup>

package/content/learn/concepts.mdx

@@ -0,0 +1,84 @@
+---
+title: "Concepts"
+description: "Core concepts behind Mercur — from the Medusa foundation to blocks, panels, and the registry."
+---
+
+Mercur is built on a small set of concepts. Familiarity with these establishes a common language when working with the platform.
+
+## Medusa
+
+[MedusaJS](https://medusajs.com) is the open-source commerce framework that powers Mercur's foundation. It handles products, pricing, carts, orders, payments, fulfillment, and promotions. Mercur does not replace any of this — it extends Medusa with marketplace-specific logic using Medusa's own extension model.
+
+## Admin Panel
+
+The admin panel is a React application for **marketplace operators**. It provides a dashboard to manage sellers, configure commission rates, moderate product requests, handle disputes, and monitor the overall marketplace. It is built with [Medusa UI](https://docs.medusajs.com/ui) components and can be extended with custom pages and components through the [Dashboard SDK](#dashboard-sdk).
+
+## Vendor Portal
+
+The vendor portal is a React application for **sellers**. Sellers use it to manage their products, process orders, configure shipping, track payouts, and handle returns. Like the admin panel, it is built on the Dashboard SDK and can be fully customized.
+
+## Storefront
+
+The storefront is the **customer-facing** application. It can be built with any frontend technology that consumes the Store API — Next.js, Remix, or any other framework. Mercur provides a ready-made storefront template to start from.
+
+## API Routes
+
+Mercur exposes three sets of HTTP endpoints:
+
+- **Admin API** (`/admin/*`) — Platform administration
+- **Vendor API** (`/vendor/*`) — Seller operations
+- **Store API** (`/store/*`) — Customer-facing storefront
+
+Each route is composed of a handler, middleware, query configuration, and validators.
+
+## Core Plugin
+
+The core plugin (`@mercurjs/core`) is the main package that contains all of Mercur's marketplace logic — modules, links, workflows, API routes, subscribers, and providers. It is installed as a standard MedusaJS plugin and serves as the foundation that blocks extend.
+
+## Modules
+
+Modules encapsulate data models and business logic for a specific domain. Each module is self-contained with its own models, service, and migrations. Mercur's marketplace modules include Seller, Commission, Offer, Payout, Product Attribute, Product Edit, Media, Custom Fields, and Search. They communicate through [Links](#links) and [Workflows](#workflows), never directly. Additional domains — such as Reviews — ship as installable [blocks](#blocks) from the registry rather than inside the core plugin.
+
+## Master Products
+
+Products form a single **shared catalog** for the whole marketplace — a product is not owned by the seller who created it. Sellers gain the right to sell a product through eligibility assignments and sell it through [offers](#offers). See [Products](/rc/learn/products).
+
+## Offers
+
+An offer is a seller's sellable listing against a master product: their own SKU, price, inventory, and shipping profile. Many sellers can hold competing offers on the same product. See [Offers](/rc/learn/offers).
+
+## Product Attributes
+
+A typed, operator-managed attribute catalog (select, text, unit, toggle) that products reference for structured data and storefront filtering. Variant-axis attributes are backed by Medusa's native global product options. See [Product Attributes](/rc/learn/attributes).
+
+## Product Requests
+
+Vendor product submissions and edits flow through a reviewable change-request pipeline — the operator confirms, declines, or requests revisions before anything touches the shared catalog. See [Product Requests & Approvals](/rc/learn/product-requests).
+
+## Links
+
+Links define relationships between Mercur modules and Medusa core entities without modifying either side. For example, a link connects a Medusa Product to a Mercur Seller — this is how the system knows which sellers are eligible to sell which products.
+
+## Workflows
+
+Workflows coordinate multi-step operations across modules. They support compensation (automatic rollback on failure) and hooks (extension points for custom logic). For example, the checkout workflow splits a cart by seller, creates separate orders, allocates payments, and calculates commissions — all as a single atomic operation.
+
+## Blocks
+
+Blocks are the unit of distribution in Mercur. Each block is a self-contained piece of functionality — a module, a workflow, an API route, a link, or a UI extension. When you install a block, the CLI copies its source code directly into your project. You own every line and can modify anything.
+
+## Registry
+
+A registry is a collection of blocks available for installation. The official Mercur registry (`@mercurjs`) provides all marketplace blocks. You can also create and host [custom registries](/rc/tools/cli#custom-registries) for your own blocks.
+
+## CLI
+
+The [Mercur CLI](/rc/tools/cli) (`@mercurjs/cli@rc`) manages your project — scaffolding from templates, installing blocks, searching registries, generating types, and diffing local changes against upstream versions.
+
+## Dashboard SDK
+
+The [Dashboard SDK](/rc/tools/dashboard-sdk) (`@mercurjs/dashboard-sdk`) is a Vite plugin shared by the admin panel and vendor portal. It provides file-based routing, automatic navigation generation, component overrides, and i18n support.
+
+## API Client
+
+The [API Client](/rc/tools/api-client) (`@mercurjs/client`) provides type-safe access to all Mercur API endpoints. Types are generated from your actual API routes using `bunx @mercurjs/cli@rc codegen`, so requests and responses are always in sync with your backend.

package/content/learn/installation.mdx

@@ -0,0 +1,117 @@
+---
+title: "Installation"
+description: "Install Mercur and set up your marketplace project."
+---
+
+## Requirements
+
+- [Node.js v20+](https://nodejs.org/en/download) (LTS version)
+- [Bun v1.3+](https://bun.sh) (recommended package manager)
+- [Git](https://git-scm.com/downloads)
+- PostgreSQL v14+
+
+<Tip>
+  The quickest way to get PostgreSQL running locally is with Docker:
+
+  ```bash
+  docker run -d --name mercur-postgres \
+    -e POSTGRES_PASSWORD=postgres \
+    -p 5432:5432 postgres:16
+  ```
+
+  Or on macOS with Homebrew:
+
+  ```bash
+  brew install postgresql@16 && brew services start postgresql@16
+  ```
+</Tip>
+
+## Create a new project
+
+```bash
+bun create mercur-app@rc
+```
+
+The CLI will prompt for a project name and template, then handle everything automatically:
+- downloads the template
+- installs dependencies
+- creates and migrates the database
+- seeds initial data
+- starts the development server and opens the admin setup page in your browser
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--template <template>` | Template to use (`basic` or `plugin`) | prompted |
+| `--db-connection-string <string>` | Full PostgreSQL connection string | — |
+| `--db-host <host>` | PostgreSQL host | `localhost` |
+| `--db-port <port>` | PostgreSQL port | `5432` |
+| `--no-deps` | Skip dependency installation | — |
+| `--skip-db` | Skip database setup | — |
+
+## Access your marketplace
+
+Once the development server is running, your marketplace is available at:
+
+| Panel | URL |
+|-------|-----|
+| API | `http://localhost:9000` |
+| Admin Panel | `http://localhost:9000/dashboard` |
+| Vendor Panel | `http://localhost:9000/seller` |
+
+### Create an admin account
+
+The CLI automatically opens the admin invite page in your browser after setup. Follow the on-screen instructions to create your first admin account.
+
+### Create your first seller
+
+The seed data does not include a seller account. To create one, open the Vendor Panel and register:
+
+```
+http://localhost:9000/seller/register
+```
+
+Fill in the registration form and complete the onboarding wizard. Once submitted, the seller will appear in the Admin Panel for approval.
+
+## Start the development server
+
+After stopping the server, start it again from your project directory:
+
+```bash
+cd <your-project-name>
+bun dev
+```
+
+## Initialize an existing project
+
+If you have an existing Medusa project, initialize Mercur in it:
+
+```bash
+bunx @mercurjs/cli@rc init
+```
+
+This creates a `blocks.json` configuration file in your project.
+
+## Add blocks
+
+Install blocks from the registry:
+
+```bash
+bunx @mercurjs/cli@rc add <block-name>
+```
+
+Browse available blocks:
+
+```bash
+bunx @mercurjs/cli@rc search
+```
+
+## Run database migrations
+
+After adding blocks that include modules:
+
+```bash
+bunx medusa db:generate <module1> <module2> ...
+bunx medusa db:migrate
+```

package/content/learn/introduction.mdx

@@ -0,0 +1,71 @@
+---
+title: "Introduction"
+description: "Mercur is an open-source marketplace platform built on MedusaJS with a block-based architecture."
+---
+
+Mercur is an open-core **marketplace platform** built on top of the [Medusa Framework](https://medusajs.com). It follows a block-based architecture — install only the modules, workflows, API routes, and UI extensions you need directly into your project. No black-box dependencies, full code ownership.
+
+## What is Mercur
+
+Medusa provides the underlying commerce engine — products, pricing, carts, orders, fulfillment, and events — while Mercur builds the marketplace domain layer on top of it.
+
+On top of Medusa's core, Mercur introduces marketplace entities and workflows such as sellers, onboarding, product requests, commissions, reviews, return escalations, order splitting, vendor payouts, and dedicated Admin, Vendor, and Storefront APIs.
+
+It comes with three optional interfaces:
+
+- an **Admin Panel** for marketplace operators
+- a **Vendor Portal** for seller teams
+- a **Storefront** ready for marketplace scenarios
+
+## Why Mercur
+
+### Built on a modern stack
+
+Mercur runs on a modern TypeScript backend powered by the Medusa framework, giving you a proven foundation for products, carts, orders, promotions, and payments. It integrates with technologies like Resend (notifications), Algolia (search), and Stripe Connect (payouts) — all replaceable when needed.
+
+### Block-based architecture
+
+Unlike traditional plugins, Mercur uses a **block-based** approach. Blocks are copied directly into your project via the CLI, giving you full ownership and the ability to modify any piece of code without forking.
+
+### Full extensibility and ownership
+
+Mercur is fully open-core and MIT-licensed. There are no transaction fees, no commercial lock-in, and no constraints on how your marketplace must behave. You own the entire codebase and can host it anywhere.
+
+## Building with AI
+
+Mercur is designed so AI agents can build and extend your marketplace safely — not by generating code from scratch, but by working within structured guardrails.
+
+### How AI works with Mercur
+
+Most AI coding tools generate loose snippets that you have to wire together yourself. Mercur gives AI something better to work with: a system with clear boundaries, typed contracts, and composable units.
+
+Here's what that looks like in practice:
+
+- **Adding features via CLI** — An AI agent can run `bunx @mercurjs/cli@rc add reviews` to install a complete review system — data models, API routes, workflows, and UI — in one command. No guessing at file structure or imports. The CLI handles wiring automatically.
+- **Extending workflows without rebuilding them** — Need custom logic when an order is placed? AI can hook into the existing `complete-cart-with-split-orders` workflow and inject a step — without rewriting the entire cart flow. Medusa's workflow hooks make this safe and predictable.
+- **Generating typed integrations** — AI reads the generated route types from `bunx @mercurjs/cli@rc codegen` and produces API calls that are correct by construction. No hallucinated endpoints, no wrong payloads — the types are the source of truth.
+- **Building UI pages** — AI can scaffold an admin or vendor page by creating a file in `src/routes/`. The dashboard SDK picks it up automatically through file-based routing. No manual route registration, no config files to update.
+- **Modifying blocks it can diff** — AI can compare local code against the registry with `bunx @mercurjs/cli@rc diff`, understand what changed, and make targeted modifications instead of blind overwrites.
+
+### Connect your AI tools
+
+To start building with AI, connect your environment to Mercur's knowledge base:
+
+- **[Building with AI](/rc/resources/ai/overview)** — How Mercur bundles version-matched docs into your project so agents build from accurate APIs, not stale training data
+- **[LLMs](/rc/resources/ai/llms)** — Feed the full Mercur documentation to any LLM via `llms.txt`
+- **[MCP Server](/rc/resources/ai/mcp)** — Let your AI tool search Mercur docs in real time (Cursor, VS Code, Claude, Claude Code)
+
+### Why this matters
+
+Traditional commerce platforms give AI no structure to reason about. The result is generated code that looks plausible but breaks in production — wrong API shapes, missing relationships, incompatible data models.
+
+Mercur solves this with:
+
+- **Typed API Client** — API specifications shared between server and client. AI reads real types, not documentation that may be outdated.
+- **Block Registry** — Features are discrete, well-defined units. AI can inspect what a block contains before installing it and verify the result after.
+- **Monorepo** — Backend, admin, vendor, and shared packages live in one workspace. AI has full context without jumping between repositories.
+- **Core Workflows** — Cart, orders, pricing, and vendor logic are exposed as structured steps. AI extends them through hooks rather than patching source code.
+- **Dashboard SDK** — File-based routing and virtual modules mean AI adds pages and components by creating files in the right place. The SDK handles registration.
+- **Marketplace Payments** — Payout providers follow a pluggable interface. AI can implement a new provider by conforming to the contract, not by reverse-engineering Stripe integration code.
+
+The result: AI agents can compose real marketplace systems — not just write code, but add capabilities, extend business logic, and evolve your architecture with guardrails that prevent mistakes.

package/content/learn/offers.mdx

@@ -0,0 +1,78 @@
+---
+title: "Offers"
+description: "An offer is a seller's sellable listing against a master product — their own SKU, price, inventory, and shipping."
+---
+
+An **offer** is how a seller actually sells something. While [products](/rc/learn/products) form a shared master catalog, an offer binds one seller to one product variant with the seller's own commercial terms: SKU, price, stock, and shipping profile. Many sellers can hold offers against the same variant, each competing on price and availability.
+
+## Data model
+
+| Field | Description |
+|-------|-------------|
+| `id` | Prefixed with `offer_` |
+| `seller_id` | The seller who owns the listing |
+| `product_id` / `variant_id` | The master catalog entry the offer sells |
+| `sku` | The seller's own SKU — unique per seller |
+| `ean` / `upc` | Optional barcodes, searchable |
+| `shipping_profile_id` | The seller's shipping profile used to fulfill this offer |
+| `created_by` | The member who created the offer |
+| `metadata` | Free-form JSON |
+
+The `(seller_id, sku)` pair is unique: a seller cannot list the same SKU twice.
+
+## Relationships
+
+Offers sit at the center of the seller's commercial graph. Module links connect each offer to:
+
+- **Seller** — the listing owner
+- **Product and variant** — the master catalog entry
+- **Price** — offer-scoped pricing (see below)
+- **Inventory item** — offer-scoped stock (see below)
+- **Shipping profile** — how the offer ships
+- **Cart and order line items** — which offer a purchased line came from
+
+### Offer-scoped pricing
+
+Offers share the variant's price set, scoped by an offer rule — each offer carries its own prices without duplicating the variant. The storefront computes a `calculated_price` per offer, so two sellers listing the same variant can show different prices side by side.
+
+### Offer-scoped inventory
+
+Inventory is linked to the **offer, not the variant**. Each seller manages stock for their own listing independently; a variant has no marketplace-wide stock figure of its own.
+
+<Warning>
+  When working with offer orders, read inventory through the offer link. The variant's own `inventory_items` relation is empty for offer-based listings.
+</Warning>
+
+## Offers at checkout
+
+When a customer buys, the cart line item links to the specific offer that was purchased. The link is preserved onto the order line item, so fulfillment, commission calculation, and payouts all resolve to the right seller — even when several sellers list the same variant.
+
+## Discovery
+
+The Store API exposes offers directly:
+
+```bash
+curl "http://localhost:9000/store/offers?product_id=prod_123" \
+  -H "x-publishable-api-key: <key>"
+```
+
+This powers "buy box"-style storefronts: fetch a product from the shared catalog, then list every seller's offer against it with per-offer calculated prices.
+
+## Where offers appear
+
+| Surface | Capability |
+|---------|-----------|
+| Vendor Portal | Full lifecycle — create offers, edit price and stock, manage variants and inventory |
+| Admin Panel | Oversight — list and inspect all offers with their store, pricing, inventory, and the associated master product |
+| Store API | Browse offers per product, with per-offer calculated prices |
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Products" href="/rc/learn/products">
+    The shared master catalog offers are built on.
+  </Card>
+  <Card title="Order Groups" href="/rc/learn/order-groups">
+    How multi-seller purchases split into per-seller orders.
+  </Card>
+</CardGroup>

package/content/learn/order-groups.mdx

@@ -0,0 +1,114 @@
+---
+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 order and the cart's payment collection
+   - Each seller and the customer (if new relationship)
+6. **Finalize** — Inventory is reserved, payment is authorized, and the `order_group.created` event is emitted
+
+<Info>
+  Payment collections are linked at the **individual order level**, not on the order group. This is a deliberate design decision — each per-seller order gets its own link to the payment collection, which enables per-order capture and refund flows.
+</Info>
+
+## 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.