@mercurjs/docs 2.2.1 → 2.3.0-canary.1

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

@@ -0,0 +1,45 @@
+---
+title: "Links to other modules"
+sidebarTitle: "Links"
+description: "How the Commission domain connects to the catalog, sellers, and orders."
+---
+
+Most Mercur modules connect to each other through **module links** (`defineLink`)
+resolved with `query.graph`. The Commission module is deliberately different: it
+defines **no** module links. Instead it connects to the rest of the marketplace
+through **soft references**. These are plain id fields resolved at calculation
+time. This keeps commission configuration independent of the catalog and order
+modules it scopes against.
+
+## Rules → catalog & sellers
+
+A `CommissionRule` points at a record in another domain through its
+`reference` / `reference_id` pair, resolved against the order line's product when
+commission is calculated:
+
+| `reference` | Points at | Resolved from |
+| --- | --- | --- |
+| `product` | A master product | `item.product.id` |
+| `product_type` | A product type | `item.product.type_id` |
+| `product_collection` | A collection | `item.product.collection_id` |
+| `product_category` | A category | `item.product.categories[].id` |
+| `seller` | A store | `item.offer.seller_id` |
+
+<Note>
+  Products are the shared master catalog, not seller-owned. The `seller`
+  dimension resolves through the **offer** on the order line, which carries the
+  selling store.
+</Note>
+
+## Lines → orders
+
+A `CommissionLine` records which order line it commissions through its
+`item_id` (an order line item) or `shipping_method_id` (a shipping method).
+These are stored as plain ids, so the payout pipeline reads an order's lines by
+querying the commission module directly rather than traversing a link.
+
+<Tip>
+  Because these are soft references, deleting a product, category, or order does
+  not cascade to commission records. Rules and lines simply stop matching or are
+  refreshed on the next order change.
+</Tip>

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

@@ -0,0 +1,51 @@
+---
+title: "Service reference"
+sidebarTitle: "Service"
+description: "The Commission module service and its methods for working with records directly."
+---
+
+The Commission 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 commissionModuleService = container.resolve(MercurModules.COMMISSION)
+
+const [rates, count] = await commissionModuleService.listAndCountCommissionRates(
+  { is_enabled: true }
+)
+```
+
+## Generated methods
+
+Each data model gets a standard set of auto-generated methods. For
+`CommissionRate`:
+
+| Method | Description |
+| --- | --- |
+| `createCommissionRates(data)` | Create one or more rates (auto-generates `code`) |
+| `retrieveCommissionRate(id, config?)` | Retrieve a rate by id |
+| `listCommissionRates(filters?, config?)` | List rates matching filters |
+| `listAndCountCommissionRates(filters?, config?)` | List rates with a total count |
+| `updateCommissionRates(data)` | Update one or more rates |
+| `deleteCommissionRates(ids)` | Delete one or more rates |
+
+The same set exists for every model in the module: `CommissionRule`,
+`CommissionRateValue`, and `CommissionLine` (e.g. `createCommissionRules`,
+`listCommissionRateValues`, `deleteCommissionLines`).
+
+## Calculation & line methods
+
+| Method | Description |
+| --- | --- |
+| `getCommissionLines(context)` | Resolve the commission lines for a calculation context (items + shipping in a currency), most-specific-wins, without persisting |
+| `upsertCommissionLines(lines)` | Replace lines by anchor (`item_id` / `shipping_method_id`), making refreshes idempotent |
+
+<Warning>
+  Prefer [workflows](/platform/commission/reference/workflows) for order-line
+  refreshes and rate deletion. `refreshOrderCommissionLinesWorkflow` builds the
+  calculation context from the order and calls these methods for you;
+  `deleteCommissionRatesWorkflow` validates that a rate is safe to delete first.
+</Warning>

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

@@ -0,0 +1,40 @@
+---
+title: "Workflows"
+sidebarTitle: "Workflows"
+description: "Commission rate, rule, and order-line workflows."
+---
+
+This reference lists the workflows for the Commission domain. Import them from
+`@mercurjs/core/workflows` and run them against the Medusa container.
+
+## Rate workflows
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `createCommissionRatesWorkflow` | `CreateCommissionRateDTO[]` | Create rates (auto-generates `code`) |
+| `updateCommissionRatesWorkflow` | `UpdateCommissionRateDTO[]` | Update rate fields |
+| `deleteCommissionRatesWorkflow` | `{ ids[] }` | Delete rates (validates deletability first) |
+
+## Rule workflows
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `batchCommissionRulesWorkflow` | `{ commission_rate_id, create?, update?, delete? }` | Create, update, and delete a rate's rules in one call |
+
+## Order-line workflows
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `refreshOrderCommissionLinesWorkflow` | `{ order_ids[] }` | Recompute and upsert an order's commission lines (idempotent) |
+
+<Note>
+  `deleteCommissionRatesWorkflow` exposes a `commissionRatesDeleted` hook, and
+  `batchCommissionRulesWorkflow` runs its create / update / delete steps in
+  parallel. `refreshOrderCommissionLinesWorkflow` also runs as a step inside the
+  cart-split checkout workflow.
+</Note>
+
+To work with records directly instead of through a workflow, see the
+[Service reference](/platform/commission/reference/service). To run side effects
+when an order changes, see the
+[Event reference](/platform/commission/reference/events).

package/content/platform/offer/concepts/pricing-and-inventory.mdx

@@ -0,0 +1,72 @@
+---
+title: "Pricing & inventory"
+sidebarTitle: "Pricing & inventory"
+description: "Offer-scoped prices on the shared price set, and inventory linked to the offer."
+---
+
+In this document, you'll learn how an offer carries its own price and inventory
+without owning the master variant.
+
+## Offer-scoped pricing
+
+An offer's prices don't live on a private price set. They live on the **master
+variant's shared `PriceSet`**, with each offer-owned row scoped by a
+`PriceRule` on the `offer_id` attribute. That's how many stores price the same
+variant independently: every price row Mercur writes for an offer is stamped with
+that offer's id, and reads filter the set back down to just that offer's rows.
+
+```ts
+// Every offer price row is written with an offer_id rule on the shared price set
+prices: [
+  {
+    amount: 2500,
+    currency_code: "usd",
+    rules: { offer_id: "offer_123" },
+  },
+]
+```
+
+The offer side reads its price ladder through the writable `offer ↔ price`
+list-link, so `offer.prices` resolves in a single query traversal. Each row is a
+standard Medusa money amount and supports `min_quantity` / `max_quantity` for
+quantity-break pricing.
+
+<Note>
+  Because prices sit on the shared price set scoped by `offer_id`, the master
+  variant is never mutated per store. The variant keeps a single price set, and
+  the `offer_id` rule partitions it per offer.
+</Note>
+
+## Offer-scoped inventory
+
+An offer's stock is held in Medusa `InventoryItem` records that link to the
+**offer**, not to the variant. The `offer ↔ inventory_item` link is a list-link
+whose pivot table (`offer_inventory_item`) carries a `required_quantity` column,
+so one offer can draw on several inventory items, each with its own required
+quantity.
+
+<Warning>
+  Offer inventory links to the **offer**, not the variant. `variant.inventory_items`
+  is empty for offer-based orders. Always resolve stock through
+  `offer.inventory_items`, never through the variant.
+</Warning>
+
+When you create an offer, its `inventory_items` entries each create a brand-new
+`InventoryItem` (with optional starting `stock_levels`) and link it to the offer
+in the same workflow run. An offer must have at least one inventory item.
+
+```ts
+inventory_items: [
+  {
+    sku: "ACME-WIDGET-01",
+    required_quantity: 1,
+    stock_levels: [{ location_id: "sloc_1", stocked_quantity: 50 }],
+  },
+]
+```
+
+<Tip>
+  The inventory items an offer creates are also linked to the store, so they show
+  up under the store's inventory. To change the set of items on an existing
+  offer, use the [batch inventory workflow](/platform/offer/guides/manage-offer-inventory).
+</Tip>

package/content/platform/offer/concepts/shipping.mdx

@@ -0,0 +1,48 @@
+---
+title: "Shipping"
+sidebarTitle: "Shipping"
+description: "How an offer carries its own shipping profile."
+---
+
+In this document, you'll learn how an offer determines how its items ship.
+
+## Shipping profile
+
+Every offer points at a store's own **shipping profile** through its
+`shipping_profile_id` field, joined via the read-only `offer ↔ shipping_profile`
+link. The profile is what ties the offer's items to the store's shipping options
+at checkout, so each store fulfills its slice of a multi-seller cart with its own
+rates.
+
+```ts
+await createOffersWorkflow(container).run({
+  input: {
+    offers: [
+      {
+        seller_id: "sel_123",
+        created_by: "mem_123",
+        variant_id: "variant_123",
+        shipping_profile_id: "sp_123",
+        sku: "ACME-WIDGET-01",
+        prices: [{ amount: 2500, currency_code: "usd" }],
+        inventory_items: [{ stock_levels: [{ location_id: "sloc_1", stocked_quantity: 50 }] }],
+      },
+    ],
+  },
+})
+```
+
+## Master products carry no profile
+
+Master products live in the shared catalog and have no shipping profile of their
+own. To keep multi-seller carts from losing their shipping methods on refresh,
+`createOffersWorkflow` links the offer's **master product** to the offer's
+shipping profile. The product↔profile link is one-to-one, so the first offer's
+profile wins for a given master product. Later offers (including other stores'
+offers on the same product) skip the link if a profile is already attached.
+
+<Note>
+  The one-to-one product↔profile link is a checkout-refresh accommodation, not
+  the source of truth for how a store ships. Each offer still carries its own
+  `shipping_profile_id`, which is what drives that store's fulfillment.
+</Note>

package/content/platform/offer/concepts/what-is-an-offer.mdx

@@ -0,0 +1,65 @@
+---
+title: "What is an offer"
+sidebarTitle: "What is an offer"
+description: "The offer record, how it points at a master product variant, and its SKU."
+---
+
+In this document, you'll learn what an offer is and how it relates to the shared
+master catalog.
+
+## Offer
+
+An offer is a store's listing against a master product variant, represented by
+the `Offer` data model (table `offer`, id prefix `offer`). It's a thin
+marketplace-side record: it holds the store (`seller_id`), the master variant it
+points at (`variant_id`), the master product (`product_id`), the store's own
+`sku`, optional `ean` / `upc` barcodes, and the shipping profile it ships with.
+Price and inventory are attached through links rather than stored on the row.
+
+```ts
+const { result } = await createOffersWorkflow(container).run({
+  input: {
+    offers: [
+      {
+        seller_id: "sel_123",
+        created_by: "mem_123",
+        variant_id: "variant_123",
+        shipping_profile_id: "sp_123",
+        sku: "ACME-WIDGET-01",
+        prices: [{ amount: 2500, currency_code: "usd" }],
+        inventory_items: [{ stock_levels: [{ location_id: "sloc_1", stocked_quantity: 50 }] }],
+      },
+    ],
+  },
+})
+```
+
+<Note>
+  **Products are not seller-owned.** The master product and its variants live in
+  the shared catalog. An offer never modifies the product. It points at a
+  variant and layers the store's own commercial terms on top.
+</Note>
+
+## Offer vs. master product
+
+A single master variant can back many offers, one per store that sells it. The
+`Offer` carries the identity of that particular listing:
+
+- `product_id` / `variant_id`: the master records the offer points at (joined through read-only links).
+- `seller_id`: the store that owns the offer (read-only link to the store).
+- `sku`: the store's own stock-keeping unit for this listing.
+- `ean` / `upc`: barcodes, snapshotted off the linked variant when not supplied.
+
+<Tip>
+  A store's `sku` is **unique within that store** (`(seller_id, sku)`, enforced
+  while `deleted_at IS NULL`). Two different stores may reuse the same SKU string
+  for their own offers.
+</Tip>
+
+## One offer per variant
+
+Each offer points at exactly one variant, so a store's offers on a product mirror
+that product's variants. When offers are grouped by store
+(`group_by_seller`), the service computes a `variant_count` and an `offer_ids`
+list for the grouped `(product, seller)` row. The dashboards use it to act on
+all of a store's offers on a product at once.

package/content/platform/offer/guides/bulk-create-offers.mdx

@@ -0,0 +1,84 @@
+---
+title: "Bulk-create offers"
+sidebarTitle: "Bulk-create offers"
+description: "List many offers against the master catalog in a single workflow run."
+---
+
+In this guide, you'll learn how to create many offers at once, for example when
+onboarding a store's catalog or running a CSV import.
+
+`createOffersWorkflow` accepts an array of offers, so a single run can list a
+store against many master variants at once. Each entry is independent and carries
+its own SKU, prices, inventory, and shipping profile.
+
+## Run the workflow with many offers
+
+```ts title="src/api/custom/bulk/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { createOffersWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const { result } = await createOffersWorkflow(req.scope).run({
+    input: {
+      offers: [
+        {
+          seller_id: "sel_123",
+          created_by: "mem_123",
+          variant_id: "variant_a",
+          shipping_profile_id: "sp_123",
+          sku: "ACME-A-01",
+          prices: [{ amount: 2500, currency_code: "usd" }],
+          inventory_items: [{ stock_levels: [{ location_id: "sloc_1", stocked_quantity: 50 }] }],
+        },
+        {
+          seller_id: "sel_123",
+          created_by: "mem_123",
+          variant_id: "variant_b",
+          shipping_profile_id: "sp_123",
+          sku: "ACME-B-01",
+          prices: [{ amount: 4000, currency_code: "usd" }],
+          inventory_items: [{ stock_levels: [{ location_id: "sloc_1", stocked_quantity: 20 }] }],
+        },
+      ],
+    },
+  })
+
+  res.status(201).json({ offers: result })
+}
+```
+
+<Warning>
+  The batch is validated as a whole: if any entry references a missing variant,
+  omits its inventory items, or reuses an existing `(seller_id, sku)` pair, the
+  run fails and its steps are compensated, so no partial offers are left behind.
+</Warning>
+
+## Update many offers
+
+`updateOffersWorkflow` mirrors the same array shape for edits. Each entry is
+keyed by the offer `id`; supplying a `prices` array **replaces** the offer's
+price ladder (rows with an `id` are updated in place, rows without one are added,
+and omitted rows are removed), while leaving `prices` out keeps the ladder
+untouched.
+
+```ts
+import { updateOffersWorkflow } from "@mercurjs/core/workflows"
+
+await updateOffersWorkflow(req.scope).run({
+  input: {
+    offers: [
+      { id: "offer_a", sku: "ACME-A-02" },
+      {
+        id: "offer_b",
+        prices: [{ amount: 3500, currency_code: "usd" }],
+      },
+    ],
+  },
+})
+```
+
+<Tip>
+  Both workflows emit one event per affected offer (`offer.created` /
+  `offer.updated`). Subscribe to those events to run downstream side effects like
+  re-indexing search. See the [Event reference](/platform/offer/reference/events).
+</Tip>

package/content/platform/offer/guides/create-an-offer.mdx

@@ -0,0 +1,83 @@
+---
+title: "Create an offer"
+sidebarTitle: "Create an offer"
+description: "Create a single offer programmatically with createOffersWorkflow."
+---
+
+In this guide, you'll learn how to create an offer from your own server code,
+for example in a custom API route, a seed script, or an import flow.
+
+Mercur exposes a `createOffersWorkflow` that creates the `Offer` record, its
+inventory items, and its price rows, and wires up every link in one run. Run it
+from any place that has access to the Medusa container.
+
+## Run the workflow
+
+```ts title="src/api/custom/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { createOffersWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const { result } = await createOffersWorkflow(req.scope).run({
+    input: {
+      offers: [
+        {
+          seller_id: "sel_123",
+          created_by: "mem_123",
+          variant_id: "variant_123",
+          shipping_profile_id: "sp_123",
+          sku: "ACME-WIDGET-01",
+          prices: [{ amount: 2500, currency_code: "usd" }],
+          inventory_items: [
+            {
+              stock_levels: [{ location_id: "sloc_1", stocked_quantity: 50 }],
+            },
+          ],
+        },
+      ],
+    },
+  })
+
+  res.status(201).json({ offer: result[0] })
+}
+```
+
+<Note>
+  Each offer must reference an existing master `variant_id` and include at least
+  one `inventory_items` entry. The SKU must be unique within the store.
+  Reusing an existing `(seller_id, sku)` pair is rejected.
+</Note>
+
+## What the workflow wires up
+
+A single run does more than insert a row:
+
+- Creates a new `InventoryItem` per `inventory_items` entry (with any `stock_levels`) and links each to the offer. Remember, inventory links to the **offer**, not the variant.
+- Writes each price onto the master variant's shared price set, stamped with an `offer_id` rule, and links the price rows to the offer.
+- Links the offer to its store, product, variant, and shipping profile.
+- Emits `offer.created`.
+
+## Attach custom data
+
+The workflow accepts an `additional_data` payload that is passed to its
+`offersCreated` hook, letting you persist marketplace-specific data alongside the
+offer without forking the workflow.
+
+```ts
+await createOffersWorkflow(req.scope).run({
+  input: {
+    offers: [
+      {
+        seller_id: "sel_123",
+        created_by: "mem_123",
+        variant_id: "variant_123",
+        shipping_profile_id: "sp_123",
+        sku: "ACME-WIDGET-01",
+        prices: [{ amount: 2500, currency_code: "usd" }],
+        inventory_items: [{ stock_levels: [{ location_id: "sloc_1", stocked_quantity: 50 }] }],
+      },
+    ],
+    additional_data: { source: "csv-import" },
+  },
+})
+```

package/content/platform/offer/guides/manage-offer-inventory.mdx

@@ -0,0 +1,53 @@
+---
+title: "Manage offer inventory"
+sidebarTitle: "Manage offer inventory"
+description: "Attach, update, and detach inventory items on an existing offer."
+---
+
+In this guide, you'll learn how to change the inventory items linked to an
+existing offer from your own server code.
+
+Because inventory links to the **offer** (not the variant), the set of inventory
+items backing an offer is managed through the `offer ↔ inventory_item` link.
+`batchOfferInventoryItemsWorkflow` applies creates, updates, and deletes to that
+link in a single run.
+
+## Run the batch workflow
+
+```ts title="src/api/custom/offer-inventory/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { batchOfferInventoryItemsWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const { result } = await batchOfferInventoryItemsWorkflow(req.scope).run({
+    input: {
+      offer_id: "offer_123",
+      create: [{ inventory_item_id: "iitem_new", required_quantity: 2 }],
+      update: [{ inventory_item_id: "iitem_existing", required_quantity: 5 }],
+      delete: ["iitem_stale"],
+    },
+  })
+
+  res.json(result)
+}
+```
+
+The result reports the links that were `created`, `updated`, and `deleted`.
+
+## Rules the workflow enforces
+
+- Items in `create` must **not** already be linked to the offer; items in `update` and `delete` **must** already be linked.
+- An `inventory_item_id` can't appear in more than one section, and can't be duplicated within a section.
+- `create` items must reference existing `InventoryItem` records; `required_quantity` defaults to `1`.
+- Deleting an item that isn't linked to the offer surfaces a 404 rather than silently no-op'ing.
+
+<Note>
+  This workflow manages the **links** between an offer and existing inventory
+  items and their `required_quantity`. To create brand-new inventory items with
+  starting stock as part of listing an offer, pass `inventory_items` to
+  [`createOffersWorkflow`](/platform/offer/guides/create-an-offer) instead.
+</Note>
+
+The workflow emits `offer.updated` and exposes an `offerInventoryItemsBatched`
+hook carrying the `offer_id`, the batch result, and any `additional_data` you
+passed in.

package/content/platform/offer/overview.mdx

@@ -0,0 +1,84 @@
+---
+title: "Offer"
+sidebarTitle: "Overview"
+description: "How a store sells against the shared master catalog, with its own SKU, price, inventory, and shipping."
+---
+
+Use offers to let each store sell against Mercur's shared master catalog on its
+own terms.
+
+The offer is the central concept of the marketplace. Products live in a single
+**master catalog** that no store owns; an offer is the record that connects a
+store to a master product variant. It carries everything that makes that listing
+the store's own: its SKU, its price, its inventory, and its shipping profile.
+Cart and order line items link back to the exact offer that was purchased, so the
+whole order lifecycle knows which store fulfills and gets paid.
+
+<Note>
+  **Products are shared; offers are owned.** A store never owns a product. It
+  publishes an offer against a master product variant. Two stores selling the
+  same product each have their own offer, with their own SKU, price, and stock.
+</Note>
+
+## Key features
+
+- **Per-store listings:** one offer per store per variant, each with its own SKU (unique within a store).
+- **Offer-scoped pricing:** prices live on the master variant's shared price set, scoped by an `offer_id` rule so every store prices independently.
+- **Offer-scoped inventory:** inventory items link to the **offer**, not the variant, so stock never leaks between stores.
+- **Per-offer shipping:** each offer points at the store's own shipping profile.
+- **Order attribution:** cart and order line items link to the purchased offer, driving fulfillment, commission, and payouts.
+- **Bulk operations:** create and update many offers, and batch an offer's inventory links, in a single workflow run.
+
+## Get started
+
+Learn how the domain fits together:
+
+<CardGroup cols={2}>
+  <Card title="What is an offer" icon="tag" href="/platform/offer/concepts/what-is-an-offer">
+    The offer record, how it points at a master variant, and its SKU.
+  </Card>
+  <Card title="Pricing & inventory" icon="coins" href="/platform/offer/concepts/pricing-and-inventory">
+    Offer-scoped prices on the shared price set and offer-linked inventory.
+  </Card>
+  <Card title="Shipping" icon="truck" href="/platform/offer/concepts/shipping">
+    How an offer carries its own shipping profile.
+  </Card>
+</CardGroup>
+
+## Examples
+
+Build against the Offer domain in your own code:
+
+<CardGroup cols={2}>
+  <Card title="Create an offer" icon="plus" href="/platform/offer/guides/create-an-offer">
+    Run `createOffersWorkflow` with a price and inventory.
+  </Card>
+  <Card title="Bulk-create offers" icon="layer-group" href="/platform/offer/guides/bulk-create-offers">
+    List many offers against the catalog in one run.
+  </Card>
+  <Card title="Manage offer inventory" icon="boxes-stacked" href="/platform/offer/guides/manage-offer-inventory">
+    Attach, update, and detach inventory items on an offer.
+  </Card>
+</CardGroup>
+
+## Resources
+
+Data models, workflows, service methods, and events for the Offer domain:
+
+<CardGroup cols={2}>
+  <Card title="Data models" icon="table" href="/platform/offer/reference/data-models">
+    The `Offer` entity and its fields.
+  </Card>
+  <Card title="Links" icon="link" href="/platform/offer/reference/links">
+    How the Offer domain links to other modules.
+  </Card>
+  <Card title="Workflows" icon="diagram-project" href="/platform/offer/reference/workflows">
+    Create, update, delete, and inventory-batch workflows.
+  </Card>
+  <Card title="Service" icon="gear" href="/platform/offer/reference/service">
+    Module service methods for working with records directly.
+  </Card>
+  <Card title="Events" icon="bell" href="/platform/offer/reference/events">
+    Events emitted as offers change.
+  </Card>
+</CardGroup>