@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/platform/offer/reference/data-models.mdx

@@ -0,0 +1,56 @@
+---
+title: "Data models"
+sidebarTitle: "Data models"
+description: "The data models owned by the Offer domain."
+---
+
+The Offer domain is owned by the **Offer module**. This reference lists its data
+model and fields. For the full module overview, see the
+[Offer overview](/platform/offer/overview).
+
+## Offer
+
+Table `offer`, id prefix `offer`. A store's listing against a master product
+variant. Price and inventory are attached through links rather than stored on the
+row.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | text | Primary key |
+| `seller_id` | text | The store that owns the offer (read-only link) |
+| `variant_id` | text | The master `ProductVariant` the offer points at |
+| `product_id` | text | The master `Product` the variant belongs to |
+| `shipping_profile_id` | text | The store's shipping profile for this offer |
+| `sku` | text | Searchable; unique within a store (see below) |
+| `ean` | text | Nullable, searchable; snapshotted off the variant when omitted |
+| `upc` | text | Nullable, searchable; snapshotted off the variant when omitted |
+| `created_by` | text | The member that created the offer |
+| `variant_count` | number | Computed; only set when grouping by store |
+| `metadata` | json | Nullable |
+
+Uniqueness: `(seller_id, sku)` is unique while `deleted_at IS NULL`, so a store
+can't reuse a SKU across its live offers, but different stores may share SKU
+strings. Indexes also cover `variant_id`, `product_id`, `seller_id`,
+`shipping_profile_id`, `ean`, and `upc`.
+
+## Linked data
+
+The offer's price ladder, inventory, and related records aren't columns on the
+`offer` table. They're joined through links and only present when requested:
+
+| Relation | Source |
+| --- | --- |
+| `prices` | Offer-owned rows on the master variant's shared price set (`offer ↔ price` list-link) |
+| `inventory_items` | `offer ↔ inventory_item` list-link; each row carries `required_quantity` |
+| `seller` | Read-only `offer ↔ seller` link |
+| `product` / `product_variant` | Read-only `offer ↔ product` / `offer ↔ variant` links |
+| `shipping_profile` | Read-only `offer ↔ shipping_profile` link |
+
+<Note>
+  `variant_count` (and the companion `offer_ids` list) are computed only when
+  offers are listed grouped by store (`group_by_seller`). On ungrouped reads they
+  are absent.
+</Note>
+
+See the [Links reference](/platform/offer/reference/links) for the full set of
+module links.

package/content/platform/offer/reference/events.mdx

@@ -0,0 +1,39 @@
+---
+title: "Event reference"
+sidebarTitle: "Events"
+description: "Events emitted by the Offer domain, for subscribers and side effects."
+---
+
+The Offer domain emits events as offers change. Subscribe to them to run side
+effects instead of polling, such as re-indexing search, syncing external
+systems, or kicking off follow-up workflows.
+
+```ts title="src/subscribers/offer-created.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+
+export default async function offerCreatedHandler({
+  event,
+  container,
+}: SubscriberArgs<{ id: string; product_id: string }>) {
+  const offerId = event.data.id
+  // ...re-index the offer, notify the store, etc.
+}
+
+export const config: SubscriberConfig = {
+  event: "offer.created",
+}
+```
+
+## Offer events
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `offer.created` | An offer is created | `{ id, product_id }` |
+| `offer.updated` | An offer's row, prices, or inventory links change | `{ id, product_id }` |
+| `offer.deleted` | An offer is deleted | `{ id, product_id }` |
+
+<Note>
+  `createOffersWorkflow` and `updateOffersWorkflow` emit one event per affected
+  offer. `batchOfferInventoryItemsWorkflow` emits `offer.updated` with a single
+  `{ id }` payload for the batched offer.
+</Note>

package/content/platform/offer/reference/links.mdx

@@ -0,0 +1,60 @@
+---
+title: "Links to other modules"
+sidebarTitle: "Links"
+description: "How the Offer domain links to other modules across the marketplace."
+---
+
+Modules in Mercur never reference each other directly. They connect through
+**module links**. The offer sits at the center of the marketplace, so it links
+out to the store, the master catalog, pricing, inventory, fulfillment, and the
+cart and order line items that reference it. Once a link is defined, you retrieve
+related records with `query.graph` using the link alias.
+
+```ts
+const { data: offers } = await query.graph({
+  entity: "offer",
+  fields: ["id", "sku", "prices.*", "inventory_items.*", "seller.name"],
+})
+```
+
+## Catalog & store
+
+| Linked module | Relationship |
+| --- | --- |
+| **Product** | An offer points at one master product (`offer.product_id`, read-only). |
+| **Product variant** | An offer points at one master variant (`offer.variant_id`, read-only). |
+| **Seller** | An offer belongs to one store (`offer.seller_id`, read-only). |
+
+## Pricing & inventory
+
+| Linked module | Relationship |
+| --- | --- |
+| **Price** | An offer has many prices: a writable list-link to the offer-owned rows on the master variant's shared price set. |
+| **Inventory item** | An offer has many inventory items: a writable list-link (`offer_inventory_item`) whose pivot carries a `required_quantity` column. |
+
+## Fulfillment
+
+| Linked module | Relationship |
+| --- | --- |
+| **Shipping profile** | An offer ships with one shipping profile (`offer.shipping_profile_id`, read-only). |
+
+## Cart & order
+
+| Linked module | Relationship |
+| --- | --- |
+| **Cart line item** | A cart line item links to the offer it added; one offer can back many cart line items (list-link on the line-item side). |
+| **Order line item** | An order line item links to the purchased offer; one offer can back many order line items across child orders (list-link on the line-item side). |
+
+<Note>
+  Read-only links (Product, Variant, Seller, Shipping profile) resolve from a
+  field on the `offer` row and can't be written through the link itself. The
+  Price and Inventory-item links are writable and are managed by the offer
+  workflows.
+</Note>
+
+<Tip>
+  The cart- and order-line-item links are list-links **on the line-item side** so
+  the same offer can be added to many carts and placed on many orders. Without
+  that, Medusa would enforce a 1:1 line-item ↔ offer relationship and block
+  re-use.
+</Tip>

package/content/platform/offer/reference/service.mdx

@@ -0,0 +1,53 @@
+---
+title: "Service reference"
+sidebarTitle: "Service"
+description: "The Offer module service and its methods for working with records directly."
+---
+
+The Offer module exposes a service you can resolve from the Medusa container to
+read and write records directly, without going through a workflow. Use it inside
+custom services, subscribers, or scheduled jobs.
+
+```ts
+import { MercurModules } from "@mercurjs/types"
+
+const offerModuleService = container.resolve(MercurModules.OFFER)
+
+const [offers, count] = await offerModuleService.listAndCountOffers({
+  seller_id: "sel_123",
+})
+```
+
+## Generated methods
+
+The `Offer` model gets a standard set of auto-generated methods:
+
+| Method | Description |
+| --- | --- |
+| `createOffers(data)` | Create one or more offers |
+| `retrieveOffer(id, config?)` | Retrieve an offer by id |
+| `listOffers(filters?, config?)` | List offers matching filters |
+| `listAndCountOffers(filters?, config?)` | List offers with a total count |
+| `updateOffers(data)` | Update one or more offers |
+| `deleteOffers(ids)` | Delete one or more offers |
+
+## Group by seller
+
+`listOffers` and `listAndCountOffers` accept a `group_by_seller` filter. When
+set, the service collapses offers to one row per `(product, seller)` group and
+populates `variant_count` and `offer_ids` on each returned offer.
+
+```ts
+const [grouped] = await offerModuleService.listAndCountOffers({
+  product_id: "prod_123",
+  group_by_seller: true,
+})
+```
+
+<Warning>
+  The service writes the `offer` row and its computed fields directly. It does
+  **not** create the offer's prices, inventory items, or module links, and it
+  does **not** emit events or run compensation. Prefer the
+  [workflows](/platform/offer/reference/workflows) for anything that must wire up
+  pricing, inventory, or links.
+</Warning>

package/content/platform/offer/reference/workflows.mdx

@@ -0,0 +1,38 @@
+---
+title: "Workflows"
+sidebarTitle: "Workflows"
+description: "Offer workflows for creating, updating, deleting, and batching inventory."
+---
+
+This reference lists the workflows for the Offer domain. Import them from
+`@mercurjs/core/workflows` and run them against the Medusa container.
+
+## Offer workflows
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `createOffersWorkflow` | `{ offers[], additional_data? }` | Create offers with prices, inventory, and links |
+| `updateOffersWorkflow` | `{ offers[], additional_data? }` | Update offer rows and rewrite their price ladders |
+| `deleteOffersWorkflow` | `{ ids[], additional_data? }` | Delete offers |
+| `batchOfferInventoryItemsWorkflow` | `{ offer_id, create?, update?, delete?, additional_data? }` | Add, update, and detach an offer's inventory-item links |
+
+## Hooks
+
+Each workflow exposes hooks so you can extend it without forking:
+
+| Workflow | Hooks |
+| --- | --- |
+| `createOffersWorkflow` | `validate`, `offersCreated` |
+| `updateOffersWorkflow` | `validate`, `offersUpdated` |
+| `deleteOffersWorkflow` | `offersDeleted` |
+| `batchOfferInventoryItemsWorkflow` | `validate`, `offerInventoryItemsBatched` |
+
+## Behavior notes
+
+- **Prices** are written on the master variant's shared price set, each row scoped by an `offer_id` `PriceRule`. On update, supplying `prices` replaces the ladder with the given rows; omitting it leaves prices untouched.
+- **Inventory** items passed to `createOffersWorkflow` are created and linked to the offer (and the store) in the same run. Every offer needs at least one.
+- Workflows run with compensation, so a failed create rolls back the inventory items, prices, and links it had already created.
+
+To work with records directly instead of through a workflow, see the
+[Service reference](/platform/offer/reference/service). To run side effects when
+an offer changes, see the [Event reference](/platform/offer/reference/events).

package/content/platform/order-group/concepts/computed-totals.mdx

@@ -0,0 +1,59 @@
+---
+title: "Computed totals"
+sidebarTitle: "Computed totals"
+description: "Why an order group's seller count and total are derived at query time, not stored."
+---
+
+This page covers how an order group's `seller_count` and `total` are calculated
+and why they aren't persisted.
+
+## Computed, not stored
+
+Two fields on the `OrderGroup` model are marked `computed()`. They never hold a
+value in the `order_group` row.
+
+```ts
+const OrderGroup = model.define("order_group", {
+  // ...
+  seller_count: model.number().computed(),
+  total: model.bigNumber().computed(),
+})
+```
+
+`seller_count` is the number of distinct sellers with a child order in the group.
+`total` is the sum of those child orders' current totals. Both are resolved
+by aggregating across the group's linked orders each time the group is read,
+rather than being written once at creation.
+
+<Note>
+  Storing these values would immediately go stale: child orders can be refunded,
+  returned, or canceled after the group is created, changing both the total and,
+  effectively, the active seller set.
+</Note>
+
+## How they're aggregated
+
+When you read a group, the Seller module's order-group repository joins the group
+to its child orders (and each order to its seller and order summary) and folds
+them up:
+
+- `seller_count`: a distinct count of the linked sellers
+- `total`: the sum of each child order's current order total
+
+```ts
+const orderGroup = await sellerModuleService.retrieveOrderGroup("og_123")
+// orderGroup.seller_count -> e.g. 3
+// orderGroup.total        -> e.g. 24900 (sum across child orders)
+```
+
+<Tip>
+  Because `total` is a `bigNumber`, group totals stay precise no matter how many
+  child orders and currencies contribute to the aggregate.
+</Tip>
+
+## Aggregated child statuses
+
+The retrieve and list workflows layer the same idea onto child orders. They
+derive each order's `payment_status` and `fulfillment_status` from its payment
+collections and fulfillments at read time, so the group reflects the live state
+of every seller's slice without any denormalized status column.

package/content/platform/order-group/concepts/order-splitting.mdx

@@ -0,0 +1,61 @@
+---
+title: "Order splitting"
+sidebarTitle: "Order splitting"
+description: "How a multi-seller cart becomes a group of independent per-seller orders."
+---
+
+This page covers how a single cart spanning multiple sellers is split into
+per-seller orders at checkout.
+
+## Why carts are split
+
+A marketplace cart can hold offers from many different sellers. Each seller
+fulfills, ships, and settles independently, so a single combined order would be
+impossible to operate. Instead, on completion the cart is divided along seller
+boundaries. Every seller with items in the cart gets its own `Order`, and all of
+those orders are attached to one parent `OrderGroup`.
+
+The split is driven by the `completeCartWithSplitOrdersWorkflow`. It groups the
+cart's line items by the seller behind each offer, and builds one order per
+seller from that seller's items and shipping methods.
+
+```ts
+import { completeCartWithSplitOrdersWorkflow } from "@mercurjs/core/workflows"
+
+const { result } = await completeCartWithSplitOrdersWorkflow(container).run({
+  input: { cart_id: "cart_123" },
+})
+// result.order_group_id -> the parent group
+```
+
+<Note>
+  Items are grouped by `item.offer.seller_id`. Sellers list against the shared
+  master catalog through **offers**, so the offer, not the product, is what
+  ties a line item to a seller.
+</Note>
+
+## What the split produces
+
+For each seller in the cart the workflow, in one transaction:
+
+- creates a child `Order` with that seller's line items and shipping methods
+- links each order to the group (`order_group_order`) and to its seller (`order_order_seller_seller`)
+- mirrors the line-item → offer links onto the new order lines
+- splits payment captures proportionally across the child orders
+- reserves offer-scoped inventory and refreshes commission lines per order
+
+Once every child order is created, the workflow emits `order.placed` for the
+orders and `order_group.created` for the group.
+
+<Tip>
+  Promotions are attributed per seller: a seller-scoped promotion links only to
+  that seller's child order, while marketplace-wide promotions are applied as
+  cart adjustments and belong to no single order.
+</Tip>
+
+## Independent child orders
+
+After the split, each child order lives its own life. Fulfillment, returns, and
+refunds are handled per order, so one seller can ship while another is still
+preparing, without affecting the rest of the group. The group remains the
+single reference the shopper uses to see the purchase as a whole.

package/content/platform/order-group/concepts/the-order-group.mdx

@@ -0,0 +1,64 @@
+---
+title: "The order group"
+sidebarTitle: "The order group"
+description: "The aggregate record over a multi-seller purchase, its display id, and cart link."
+---
+
+This page covers the order group record and how it aggregates the per-seller
+orders created from a single cart.
+
+## Order group
+
+An order group is the shopper-facing wrapper over a multi-seller purchase. It is
+represented by the `OrderGroup` data model (table `order_group`, id prefix
+`og`). When a cart containing offers from more than one seller is completed, the
+cart is split into one child order per seller. All of those orders are attached
+to a single group.
+
+```ts
+const OrderGroup = model.define("order_group", {
+  id: model.id({ prefix: "og" }).primaryKey(),
+  display_id: model.autoincrement(),
+  seller_count: model.number().computed(),
+  customer_id: model.text().nullable(),
+  total: model.bigNumber().computed(),
+  cart_id: model.text(),
+})
+```
+
+The group carries a human-readable `display_id`, an auto-incrementing integer,
+so shoppers and operators can reference the purchase without exposing the
+internal id. `customer_id` records who placed it. `seller_count` and `total`
+are computed at read time. See [Computed totals](/platform/order-group/concepts/computed-totals).
+
+<Note>
+  A group is created even for a single-seller cart, so every completed
+  marketplace order has exactly one parent group regardless of how many sellers
+  it spans.
+</Note>
+
+## The cart link
+
+Each group holds a `cart_id` pointing back to the cart it was created from. This
+is exposed as a **read-only** link to the Cart module. The cart is frozen
+(`completed_at` is set) the moment the split runs, so the reference is a
+historical record, not something you write through.
+
+```ts
+const { data: groups } = await query.graph({
+  entity: "order_group",
+  fields: ["id", "display_id", "cart.id", "orders.id"],
+})
+```
+
+<Tip>
+  Because the cart is immutable after checkout, the `cart_id` is safe to treat as
+  a stable audit pointer to the exact basket the shopper paid for.
+</Tip>
+
+## Child orders
+
+The group doesn't store line items itself. Those live on the child `Order`
+records, linked through the `order_group_order` table. Loading a group's
+`orders.*` gives you each seller's slice, each with its own fulfillment, payment,
+returns, and refunds.

package/content/platform/order-group/guides/list-order-groups.mdx

@@ -0,0 +1,67 @@
+---
+title: "List order groups"
+sidebarTitle: "List order groups"
+description: "Page through order groups and scope them to a seller with getOrderGroupsListWorkflow."
+---
+
+In this guide, you'll learn how to list order groups from server code, page
+through the results, and optionally scope them to a single seller.
+
+Mercur exposes a `getOrderGroupsListWorkflow` that returns groups with their
+aggregated child orders and a total count for pagination.
+
+## Run the workflow
+
+```ts title="src/api/custom/order-groups/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { getOrderGroupsListWorkflow } from "@mercurjs/core/workflows"
+
+export async function GET(req: MedusaRequest, res: MedusaResponse) {
+  const { result } = await getOrderGroupsListWorkflow(req.scope).run({
+    input: {
+      fields: ["id", "display_id", "total", "seller_count"],
+      variables: {
+        skip: 0,
+        take: 20,
+        order: { created_at: "DESC" },
+      },
+    },
+  })
+
+  res.json({
+    order_groups: result.rows,
+    count: result.metadata?.count ?? 0,
+  })
+}
+```
+
+The workflow returns `{ rows, metadata }`, where `metadata` carries the `count`,
+`skip`, and `take` you need to drive pagination.
+
+<Note>
+  Filters go inside `variables`: the group repository understands `id`,
+  `customer_id`, `seller_id`, `status`, `sales_channel_id`, `created_at`,
+  `updated_at`, and a free-text `q` (matched against group id and customer id).
+</Note>
+
+## Scope to a seller
+
+Pass a `sellerId` to get a vendor's slice. The workflow filters each group's
+child orders down to that seller, so vendors only ever see their own orders
+within a group.
+
+```ts
+await getOrderGroupsListWorkflow(req.scope).run({
+  input: {
+    fields: ["id", "display_id"],
+    variables: { seller_id: "sel_123", take: 20 },
+    sellerId: "sel_123",
+  },
+})
+```
+
+<Tip>
+  Admin surfaces call this workflow with no `sellerId` for platform-wide
+  visibility. Vendor surfaces pass the resolved seller so both the query and the
+  returned child orders stay scoped to that store.
+</Tip>

package/content/platform/order-group/guides/retrieve-an-order-group.mdx

@@ -0,0 +1,63 @@
+---
+title: "Retrieve an order group"
+sidebarTitle: "Retrieve an order group"
+description: "Load an order group and its aggregated child orders with getOrderGroupDetailWorkflow."
+---
+
+In this guide, you'll learn how to load a single order group together with its
+child orders from your own server code.
+
+Mercur exposes a `getOrderGroupDetailWorkflow` that fetches the group, expands
+its child orders, and derives each order's payment and fulfillment status. Run it
+from any place that has access to the Medusa container.
+
+## Run the workflow
+
+```ts title="src/api/custom/order-group/[id]/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { getOrderGroupDetailWorkflow } from "@mercurjs/core/workflows"
+
+export async function GET(req: MedusaRequest, res: MedusaResponse) {
+  const { result: order_group } = await getOrderGroupDetailWorkflow(
+    req.scope
+  ).run({
+    input: {
+      order_group_id: req.params.id,
+      fields: ["id", "display_id", "total", "seller_count", "cart_id"],
+    },
+  })
+
+  res.json({ order_group })
+}
+```
+
+The workflow always expands the group's child orders regardless of the `fields`
+you pass, so `order_group.orders` is populated with each seller's slice.
+
+<Note>
+  The workflow only fetches heavy relations when you ask for them: include a
+  `payment_collections` field to get per-order `payment_status`, and a
+  `fulfillments` field to get `fulfillment_status`. Otherwise those collections
+  are stripped from the response to keep it lean.
+</Note>
+
+## Follow the cart link
+
+The group's read-only `cart_id` points back to the immutable cart it came from.
+Expand it through the module link when you need the original basket:
+
+```ts
+await getOrderGroupDetailWorkflow(req.scope).run({
+  input: {
+    order_group_id: req.params.id,
+    fields: ["id", "cart.id", "cart.email", "orders.id", "orders.total"],
+  },
+})
+```
+
+<Tip>
+  Prefer the workflow over reading the record directly. It does the child-order
+  status aggregation for you. The raw
+  [service method](/platform/order-group/reference/service) returns only the
+  group row and its computed totals.
+</Tip>

package/content/platform/order-group/guides/split-a-cart.mdx

@@ -0,0 +1,58 @@
+---
+title: "Split a cart into orders"
+sidebarTitle: "Split a cart"
+description: "Complete a multi-seller cart into a group of per-seller orders with completeCartWithSplitOrdersWorkflow."
+---
+
+In this guide, you'll learn how the checkout split works and how to run it from
+your own server code, such as a custom complete-cart route.
+
+Mercur replaces Medusa's single-order checkout with
+`completeCartWithSplitOrdersWorkflow`. It takes a cart that may hold offers from
+several sellers, creates one order per seller, and wraps them in an `OrderGroup`.
+
+## Run the workflow
+
+```ts title="src/api/store/carts/[id]/complete/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { completeCartWithSplitOrdersWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const { result } = await completeCartWithSplitOrdersWorkflow(req.scope).run({
+    input: { cart_id: req.params.id },
+  })
+
+  res.json({ order_group_id: result.order_group_id })
+}
+```
+
+The workflow is idempotent per cart: if a group already exists for the cart it
+returns the existing `order_group_id` instead of splitting again. It acquires a
+lock on the cart id for the duration of the split so concurrent completions can't
+create duplicate orders.
+
+<Note>
+  Line items are grouped by `item.offer.seller_id`. Sellers sell against the
+  shared master catalog through **offers**, so a line item's seller comes from
+  its offer, never from product ownership.
+</Note>
+
+## What happens during the split
+
+For the cart, the workflow validates payments and per-seller shipping, then in a
+single transaction:
+
+- creates the parent `OrderGroup` (`customer_id`, `cart_id`)
+- creates one child `Order` per seller from that seller's items and shipping
+- links each order to the group, its seller, and the originating cart
+- mirrors line-item → offer links, reserves offer inventory, and splits payment captures proportionally
+- refreshes commission lines per order and marks the cart `completed_at`
+
+Finally it emits `order.placed` for the created orders and `order_group.created`
+for the group.
+
+<Tip>
+  The workflow exposes hooks `validate`, `beforePaymentAuthorization`, and
+  `orderGroupCreated`, so you can inject marketplace-specific logic around the
+  split without forking it.
+</Tip>