@mercurjs/docs 2.3.8-canary.3 → 2.3.8-canary.4

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

@@ -1,72 +1,86 @@
 ---
-title: "Pricing & inventory"
+title: "How offer prices and stock work"
 sidebarTitle: "Pricing & inventory"
-description: "Offer-scoped prices on the shared price set, and inventory linked to the offer."
+description: "Offer prices live on the variant's shared price set behind an offer_id rule, and offer stock lives in inventory items linked to the offer."
 ---
 
-In this document, you'll learn how an offer carries its own price and inventory
-without owning the master variant.
+Several stores sell the same master variant, so prices and stock can’t live on the variant alone. Mercur keeps one price set per variant and tags each price row with the offer that owns it. Stock goes the other way: each offer gets its own inventory items, linked to the offer and never to the variant.
 
-## Offer-scoped pricing
+<img className="block dark:hidden" src="/images/figures/offer-price-rules-light.svg" alt="The shared price set of the Linen shirt M variant holds price rows for three offers; each row carries an offer_id rule, and the two rows for offer_01JD8QA form a quantity tier. Behind it, that offer links to its own inventory items." />
+<img className="hidden dark:block" src="/images/figures/offer-price-rules-dark.svg" alt="The shared price set of the Linen shirt M variant holds price rows for three offers; each row carries an offer_id rule, and the two rows for offer_01JD8QA form a quantity tier. Behind it, that offer links to its own inventory items." />
 
-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.
+## Prices on the shared price set
+
+An offer has no price set of its own. Its prices are rows on the master variant’s `PriceSet`, and each row carries a price rule with the attribute `offer_id` set to the offer’s id.
+
+When an offer is created, `ensureVariantPriceSetsStep` gives the variant a price set if it has none. The workflow then adds each price with the `offer_id` rule merged into any rules you pass, and links every new price to the offer through the `offer ↔ price` link. That link is what `offer.prices` reads.
 
 ```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" },
-  },
+  { amount: 4700, currency_code: "eur" },
+  { amount: 4200, currency_code: "eur", min_quantity: 10 },
 ]
 ```
 
-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.
+These two rows give the offer a quantity tier. Each price accepts `min_quantity`, `max_quantity`, and extra `rules`. You never write the `offer_id` rule yourself: the workflow adds it.
+
+## How the right price is picked
+
+Carts resolve offer prices through Medusa’s pricing context. Mercur hooks into `setPricingContext` on `addToCartWorkflow`, `updateLineItemInCartWorkflow`, and `refreshCartItemsWorkflow` and adds `offer_id` with the ids of the offers in the cart.
+
+The pricing module then matches only the rows whose `offer_id` rule fits. If none of the items being added resolves to an offer, `addToCartWorkflow` fails with `Every cart line item must resolve to an offer_id`.
 
-<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>
+## Replacing an offer’s prices
 
-## Offer-scoped inventory
+Updating prices replaces the offer’s own rows and leaves every other offer on the variant alone. `upsertOfferPricesWorkflow` does the work, and `updateOffersWorkflow` runs it when an entry has a `prices` array.
 
-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.
+The incoming array is the full new list:
+
+- **Row with an `id`**: updates that price in place
+- **Row without an `id`**: adds a new price with the `offer_id` rule
+- **Owned price left out**: removes the price and its link
+- **`id` owned by another offer**: the run fails with `Price … does not belong to offer …`
 
 <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.
+  Removed prices are deleted, not soft-deleted. The `offerPricesUpserted` hook payload carries `previous_prices`, which is the only place the old values can still be read.
 </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.
+## Inventory linked to the offer
+
+Offer stock lives in Medusa `InventoryItem` records linked to the offer. The `offer ↔ inventory_item` link is many-to-many and its table, `offer_inventory_item`, has a `required_quantity` column (default `1`).
+
+One offer can draw on several inventory items, which makes it a kit. Ordering 1 unit of the offer reserves `required_quantity` units of each linked item.
+
+<Warning>
+  `variant.inventory_items` is empty for offers. Read stock through the offer, never through the variant.
+</Warning>
+
+The link has two read paths in `query.graph`:
+
+- **`inventory_items`**: the `InventoryItem` rows themselves, without the pivot columns
+- **`inventory_item_link`**: the pivot rows, with `required_quantity` and a nested `inventory_item`
 
 ```ts
-inventory_items: [
-  {
-    sku: "ACME-WIDGET-01",
-    required_quantity: 1,
-    stock_levels: [{ location_id: "sloc_1", stocked_quantity: 50 }],
-  },
-]
+const { data: [offer] } = await query.graph({
+  entity: "offer",
+  fields: [
+    "inventory_item_link.required_quantity",
+    "inventory_item_link.inventory_item.location_levels.*",
+  ],
+  filters: { id: "offer_01JD8Q1234567" },
+})
 ```
 
-<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>
+## Inventory created with the offer
+
+`createOffersWorkflow` creates fresh inventory items for every offer. Each `inventory_items` entry becomes one new item with optional starting `stock_levels`, linked to the offer and to the store.
+
+Every offer needs at least one entry. The new item takes the variant’s title, and when the offer has a single item with `required_quantity` 1, it also copies the variant’s weight, dimensions, `hs_code`, `mid_code`, `origin_country`, and `material`.
+
+The offer row’s `manage_inventory` and `allow_backorder` flags drive the stock check. When `manage_inventory` is `true` and `allow_backorder` is `false`, adding the offer to a cart confirms `required_quantity` × quantity for each linked item. To change which items back an existing offer, use `batchOfferInventoryItemsWorkflow`.
+
+## Related
+
+- [Manage offer inventory](/platform/offer/guides/manage-offer-inventory)
+- [Price and inventory links](/platform/offer/reference/links)
+- [upsertOfferPricesWorkflow and its hook](/platform/offer/reference/workflows)

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

@@ -1,48 +1,47 @@
 ---
-title: "Shipping"
+title: "How an offer ships"
 sidebarTitle: "Shipping"
-description: "How an offer carries its own shipping profile."
+description: "Each offer names its store's shipping profile, and Mercur links the master product to a profile so multi-store carts keep their shipping methods."
 ---
 
-In this document, you'll learn how an offer determines how its items ship.
+Every offer ships with a shipping profile that belongs to its store. The profile ties the offer’s items to that store’s shipping options, so in a cart with items from several stores, each store ships its own items at its own rates.
 
-## Shipping profile
+## The offer’s 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.
+An offer stores its profile in `shipping_profile_id`, a required field on the `Offer` row. A read-only link on that field exposes the profile as `offer.shipping_profile` in `query.graph`.
+
+You set the profile when you create the offer and can change it with `updateOffersWorkflow`:
 
 ```ts
-await createOffersWorkflow(container).run({
+await updateOffersWorkflow(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 }] }],
-      },
+      { id: "offer_01JD8Q1234567", shipping_profile_id: "sp_01JD8Q1234567" },
     ],
   },
 })
 ```
 
-## Master products carry no profile
+This run moves one offer to a different profile and emits `offer.updated`. The offer workflows don’t check that the profile belongs to the offer’s store, so validate that in your route when the input comes from a seller.
+
+## Shipping profiles on master products
+
+Master products don’t carry a shipping profile of their own, but Medusa’s cart refresh keeps a shipping method only when a product in the cart matches the option’s profile. Without a profile on the product, multi-store carts would lose their shipping methods on every refresh.
+
+`createOffersWorkflow` closes that gap. For each master product in the run, it links the product to the offer’s shipping profile when the product has no profile yet:
 
-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.
+- **Product without a profile**: the first offer in the run sets it
+- **Product that already has a profile**: the link is skipped, even when another store’s offer names a different profile
+- **Several offers on one product in one run**: only the first offer’s profile is linked
 
 <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.
+  The product to profile link is one-to-one and exists only for the cart refresh. Each offer’s own `shipping_profile_id` is still what decides how that store ships.
 </Note>
+
+`updateOffersWorkflow` doesn’t touch the product link, so changing an offer’s profile later leaves the product’s profile as it was.
+
+## Related
+
+- [What is an offer](/platform/offer/concepts/what-is-an-offer)
+- [The offer to shipping profile link](/platform/offer/reference/links)
+- [Create an offer](/platform/offer/guides/create-an-offer)

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

@@ -1,65 +1,68 @@
 ---
 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."
+description: "The offer record, how it points at a master variant, its SKU rules, and the conditions a store can list under."
 ---
 
-In this document, you'll learn what an offer is and how it relates to the shared
-master catalog.
+An offer is a store’s listing of one master product variant. The catalog product belongs to the marketplace, and the offer holds the store’s commercial terms on top of it: SKU, barcodes, condition, shipping profile, prices, and stock. You need this split in mind before you build anything that sells, because carts, orders, commissions, and payouts all follow the offer, not the product.
 
-## Offer
+## The offer record
 
-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.
+The `Offer` data model (table `offer`, id prefix `offer`) is a thin row that points at catalog records by id. Prices and inventory aren’t columns on it: they attach through module links.
+
+The row carries these groups of fields:
+
+- **Ownership**: `seller_id` is the store, and `created_by` is the member who created the offer
+- **Catalog pointers**: `variant_id` and `product_id`, where `product_id` is read from the variant when the offer is created
+- **Identity**: `sku`, plus optional `ean` and `upc` barcodes copied from the variant when you leave them out
+- **Selling terms**: `shipping_profile_id`, `manage_inventory` (default `true`), `allow_backorder` (default `false`), and `leadtime_to_ship`
+- **Condition**: an optional `condition_id` that points at an `OfferCondition`
 
 ```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 }] }],
-      },
-    ],
-  },
+const { data: [offer] } = await query.graph({
+  entity: "offer",
+  fields: ["id", "sku", "seller.name", "product_variant.title"],
+  filters: { id: "offer_01JD8Q1234567" },
 })
 ```
 
-<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>
+This query reads one offer with its store and master variant. `seller` and `product_variant` resolve through read-only links on `seller_id` and `variant_id`.
 
-## Offer vs. master product
+## Offers and master products
 
-A single master variant can back many offers, one per store that sells it. The
-`Offer` carries the identity of that particular listing:
+A master variant can back any number of offers. Each store that sells the variant holds its own offer, and the variant itself never changes when a store lists, prices, or stocks it.
 
-- `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.
+The same store can also list a variant more than once, for example a new and a refurbished copy. The module doesn’t limit offers per variant. The only uniqueness rule is the SKU.
 
 <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.
+  A SKU is unique within a store: the index on `(seller_id, sku)` applies while `deleted_at` is null. Two stores can use the same SKU string, and a soft-deleted offer frees its SKU.
 </Tip>
 
-## One offer per variant
+## Offer conditions
+
+An offer condition describes the physical state an offer is sold in. Operators manage conditions, and stores pick one when they create or update an offer.
+
+The `OfferCondition` model (id prefix `ofcond`) has a unique `code`, a display `label`, an `is_active` flag, and a `rank` that orders the list. The create and update workflows check every `condition_id` they receive:
+
+- **Unknown id**: the run fails with a not found error
+- **Inactive condition**: the run fails, so a deactivated condition can’t be assigned to new or edited offers
+- **Condition in use**: `deleteOfferConditionsWorkflow` refuses to delete a condition while any offer still uses it
+
+Deactivating a condition leaves the offers already listed under it unchanged.
+
+## Grouping offers by store
+
+A store’s offers on one product usually mirror that product’s variants. The service can collapse them into one row per product and store.
+
+When you pass `group_by_seller: true` to `listOffers` or `listAndCountOffers`, the service returns the newest offer of each `(product_id, seller_id)` group and sets two computed fields on it:
+
+- **`variant_count`**: how many offers the store has on that product
+- **`offer_ids`**: the ids of all offers in the group
+
+Only `product_id` and `seller_id` filters apply in grouped mode.
+
+## Related
 
-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.
+- [How offer prices and stock work](/platform/offer/concepts/pricing-and-inventory)
+- [How an offer ships](/platform/offer/concepts/shipping)
+- [Offer and OfferCondition fields](/platform/offer/reference/data-models)

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

@@ -1,65 +1,84 @@
 ---
-title: "Bulk-create offers"
+title: "Create and update offers in bulk"
 sidebarTitle: "Bulk-create offers"
-description: "List many offers against the master catalog in a single workflow run."
+description: "List a store’s master variants in a single createOffersWorkflow run, then update or delete them in bulk."
 ---
 
-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 })
-}
-```
+Pass a list of entries to `createOffersWorkflow` when you onboard a store’s catalog or run an import. One run creates every offer or none of them.
+
+## Before you begin
+
+You need these records in place:
+
+- **A store and a member**: the `seller_id` and the `created_by` member id for every entry
+- **Master variants**: one `variant_id` per row you import
+- **A shipping profile and a stock location**: both owned by the store
 
 <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.
+  Keep each run to one store. The workflow links all new inventory items to the store of the first entry, so mixing stores in one run assigns the other stores’ stock to the wrong store.
 </Warning>
 
-## Update many offers
+## Import a store’s rows
+
+<Steps>
+  <Step title="Map your rows to offer entries">
+    Turn each source row into a `CreateOfferDTO` from `@mercurjs/types`.
+
+    ```ts title="src/lib/to-offers.ts"
+    import type { CreateOfferDTO } from "@mercurjs/types"
+
+    type Row = { variant_id: string; sku: string; price: number; qty: number }
+
+    export const toOffers = (rows: Row[]): CreateOfferDTO[] =>
+      rows.map((row) => ({
+        seller_id: "sel_01JD8Q1234567",
+        created_by: "mem_01JD8Q1234567",
+        shipping_profile_id: "sp_01JD8Q1234567",
+        variant_id: row.variant_id,
+        sku: row.sku,
+        prices: [{ amount: row.price, currency_code: "eur" }],
+        inventory_items: [
+          {
+            stock_levels: [
+              { location_id: "sloc_01JD8Q1234567", stocked_quantity: row.qty },
+            ],
+          },
+        ],
+      }))
+    ```
+
+    Each entry is independent and carries its own SKU, price, and starting stock.
+  </Step>
+  <Step title="Run the workflow once for the batch">
+    Call the workflow with the mapped entries.
+
+    ```ts title="src/api/admin/custom/offers/import/route.ts"
+    import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+    import { createOffersWorkflow } from "@mercurjs/core/workflows"
+    import { toOffers } from "../../../../../lib/to-offers"
+
+    export async function POST(req: MedusaRequest, res: MedusaResponse) {
+      const { rows } = req.body as { rows: Parameters<typeof toOffers>[0] }
+
+      const { result } = await createOffersWorkflow(req.scope).run({
+        input: { offers: toOffers(rows) },
+      })
+
+      res.status(201).json({ count: result.length })
+    }
+    ```
 
-`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.
+    The run emits one `offer.created` event per offer.
+  </Step>
+</Steps>
+
+<Note>
+  The batch is all or nothing. A missing variant, an entry without inventory items, or a SKU the store already uses fails the run, and compensation removes everything it created.
+</Note>
+
+## Update offers in bulk
+
+`updateOffersWorkflow` takes the same array shape, keyed by offer `id`. Every field except `id` is optional.
 
 ```ts
 import { updateOffersWorkflow } from "@mercurjs/core/workflows"
@@ -67,18 +86,35 @@ import { updateOffersWorkflow } from "@mercurjs/core/workflows"
 await updateOffersWorkflow(req.scope).run({
   input: {
     offers: [
-      { id: "offer_a", sku: "ACME-A-02" },
+      { id: "offer_01JD8Q1234567", sku: "ACME-LS-M-2" },
       {
-        id: "offer_b",
-        prices: [{ amount: 3500, currency_code: "usd" }],
+        id: "offer_01JD8Q1234568",
+        prices: [{ amount: 3900, currency_code: "eur" }],
       },
     ],
+    updated_by: "mem_01JD8Q1234567",
   },
 })
 ```
 
-<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>
+The first entry renames a SKU and keeps its prices. The second replaces that offer’s prices: send an existing price `id` to update a row in place, since rows left out are deleted. `updated_by` reaches the `offersUpdated` and `offerPricesUpserted` hooks.
+
+## Delete offers in bulk
+
+`deleteOffersWorkflow` takes a list of ids and soft-deletes the offer rows.
+
+```ts
+import { deleteOffersWorkflow } from "@mercurjs/core/workflows"
+
+await deleteOffersWorkflow(req.scope).run({
+  input: { ids: ["offer_01JD8Q1234567", "offer_01JD8Q1234568"] },
+})
+```
+
+The run emits `offer.deleted` per offer. Its `offersDeleted` hook gets a snapshot of each offer and its prices taken before the delete. The workflow has no step that removes the offer’s prices or inventory items.
+
+## Next steps
+
+- [Manage offer inventory](/platform/offer/guides/manage-offer-inventory)
+- [How offer prices are replaced](/platform/offer/concepts/pricing-and-inventory)
+- [Offer events](/platform/offer/reference/events)