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

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

@@ -1,22 +1,55 @@
 ---
-title: "Event reference"
+title: "Offer events"
 sidebarTitle: "Events"
-description: "Events emitted by the Offer domain, for subscribers and side effects."
+description: "Events the offer workflows emit, with their payloads, 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.
+The offer and offer condition workflows emit events after they write. Subscribe to them to reindex search, sync an external system, or start a follow-up workflow instead of polling.
+
+## Offer events
+
+The offer workflows emit one event per affected offer. The names come from `OfferWorkflowEvents`.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `offer.created` | `createOffersWorkflow` creates an offer | `{ id, product_id }` |
+| `offer.updated` | `updateOffersWorkflow` updates an offer | `{ id, product_id }` |
+| `offer.updated` | `batchOfferInventoryItemsWorkflow` changes an offer’s inventory links | `{ id }` |
+| `offer.deleted` | `deleteOffersWorkflow` soft-deletes an offer | `{ id, product_id }` |
+
+<Note>
+  `upsertOfferPricesWorkflow` emits no event of its own. When `updateOffersWorkflow` runs it, `offer.updated` covers the change. When you run it directly, use its `offerPricesUpserted` hook.
+</Note>
+
+## Offer condition events
+
+The condition workflows emit one event per condition. The names come from `OfferConditionWorkflowEvents`.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `offer_condition.created` | `createOfferConditionsWorkflow` creates a condition | `{ id }` |
+| `offer_condition.updated` | `updateOfferConditionsWorkflow` updates a condition | `{ id }` |
+| `offer_condition.deleted` | `deleteOfferConditionsWorkflow` deletes a condition | `{ id }` |
+
+## Subscribe to an offer event
+
+A subscriber receives the payload and the container. This one reads the new offer with its store.
 
 ```ts title="src/subscribers/offer-created.ts"
 import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
 
 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.
+  const query = container.resolve(ContainerRegistrationKeys.QUERY)
+  const { data: [offer] } = await query.graph({
+    entity: "offer",
+    fields: ["id", "sku", "seller.name"],
+    filters: { id: event.data.id },
+  })
+  container.resolve("logger").info(`${offer.seller.name} listed ${offer.sku}`)
 }
 
 export const config: SubscriberConfig = {
@@ -24,16 +57,9 @@ export const config: SubscriberConfig = {
 }
 ```
 
-## Offer events
+Payloads carry ids only, so query the offer for the fields you need. For an `offer.deleted` subscriber, read values from the `offersDeleted` hook instead, since the row is already soft-deleted.
 
-| 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 }` |
+## Related
 
-<Note>
-  `createOffersWorkflow` and `updateOffersWorkflow` emit one event per affected
-  offer. `batchOfferInventoryItemsWorkflow` emits `offer.updated` with a single
-  `{ id }` payload for the batched offer.
-</Note>
+- [Offer workflows](/platform/offer/reference/workflows)
+- [Offer module links](/platform/offer/reference/links)

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

@@ -1,60 +1,112 @@
 ---
-title: "Links to other modules"
+title: "Offer module links"
 sidebarTitle: "Links"
-description: "How the Offer domain links to other modules across the marketplace."
+description: "Every module link that connects offers to stores, the catalog, pricing, inventory, fulfillment, carts, and orders."
 ---
 
-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.
+The Offer module never references another module directly. Eight module links in `packages/core/src/links/` connect the offer to the rest of the marketplace, and `query.graph` follows them by alias.
+
+| Link | Other side | Kind | File |
+| --- | --- | --- | --- |
+| Offer to store | `Seller` | Read-only, on `seller_id` | `offer-seller-link.ts` |
+| Offer to product | `Product` | Read-only, on `product_id` | `offer-product-link.ts` |
+| Offer to variant | `ProductVariant` | Read-only, on `variant_id` | `offer-variant-link.ts` |
+| Offer to shipping profile | `ShippingProfile` | Read-only, on `shipping_profile_id` | `offer-shipping-profile-link.ts` |
+| Offer to price | `Price` | Writable, one offer to many prices | `offer-price-link.ts` |
+| Offer to inventory item | `InventoryItem` | Writable, many to many | `offer-inventory-item-link.ts` |
+| Cart line item to offer | Cart `LineItem` | Writable, many items to one offer | `cart-line-item-offer-link.ts` |
+| Order line item to offer | `OrderLineItem` | Writable, many items to one offer | `order-line-item-offer-link.ts` |
+
+## Offer to store
+
+Each offer belongs to one store. The link reads `offer.seller_id`, so you write the store by setting that field, not through the link.
+
+```ts
+const { data: offers } = await query.graph({
+  entity: "offer",
+  fields: ["id", "sku", "seller.name"],
+  filters: { seller_id: "sel_01JD8Q1234567" },
+})
+```
+
+## Offer to product and variant
+
+Each offer points at one master product and one master variant. Both links are read-only and read `offer.product_id` and `offer.variant_id`.
+
+```ts
+const { data: offers } = await query.graph({
+  entity: "offer",
+  fields: ["id", "product.title", "product_variant.title"],
+  filters: { product_id: "prod_01JD8Q1234567" },
+})
+```
+
+The variant alias is `product_variant`. Use `product_variant.price_set.id` to reach the shared price set that holds the offer’s prices.
+
+## Offer to shipping profile
+
+Each offer ships with one profile, read from `offer.shipping_profile_id`.
 
 ```ts
 const { data: offers } = await query.graph({
   entity: "offer",
-  fields: ["id", "sku", "prices.*", "inventory_items.*", "seller.name"],
+  fields: ["id", "shipping_profile.id", "shipping_profile.name"],
 })
 ```
 
-## Catalog & store
+## Offer to price
+
+One offer has many prices. The link records which rows on the variant’s shared price set belong to the offer. The offer workflows create and dismiss these links, so don’t write them yourself.
+
+```ts
+const { data: offers } = await query.graph({
+  entity: "offer",
+  fields: [
+    "prices.amount",
+    "prices.currency_code",
+    "prices.min_quantity",
+    "prices.price_rules.attribute",
+    "prices.price_rules.value",
+  ],
+})
+```
 
-| 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). |
+Every row returned also carries an `offer_id` price rule with the offer’s id.
 
-## Pricing & inventory
+## Offer to inventory item
 
-| 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. |
+Offers and inventory items link many to many. The link table is `offer_inventory_item`, with an extra `required_quantity` integer column that defaults to `1`.
 
-## Fulfillment
+The link has three aliases:
 
-| Linked module | Relationship |
-| --- | --- |
-| **Shipping profile** | An offer ships with one shipping profile (`offer.shipping_profile_id`, read-only). |
+- **`offer.inventory_items`**: the linked `InventoryItem` rows, without pivot columns
+- **`offer.inventory_item_link`**: the pivot rows, with `required_quantity` and a nested `inventory_item`
+- **`inventory_item.offers`**: the offers that draw on an inventory item
 
-## Cart & order
+```ts
+const { data: offers } = await query.graph({
+  entity: "offer",
+  fields: [
+    "inventory_item_link.required_quantity",
+    "inventory_item_link.inventory_item.sku",
+  ],
+})
+```
+
+## Cart and order line items to offer
+
+Line items link to the offer that was bought. Both links set `isList: true` on the line item side, so one offer can back line items in any number of carts and orders.
+
+```ts
+const { data: [cart] } = await query.graph({
+  entity: "cart",
+  fields: ["items.id", "items.offer.id", "items.offer.seller_id"],
+  filters: { id: "cart_01JD8Q1234567" },
+})
+```
 
-| 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). |
+The alias is `offer` on both cart and order line items. At checkout, `mirrorLineItemOfferLinksToOrderStep` copies each cart line item’s link to the new order line item. A subscriber does the same for line items added later by order edits, exchanges, and claims.
 
-<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>
+## Product to shipping profile
 
-<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>
+`createOffersWorkflow` also writes Medusa’s own product to shipping profile link when the product has none. That link is Medusa’s, not Mercur’s. See [How an offer ships](/platform/offer/concepts/shipping).

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

@@ -1,53 +1,88 @@
 ---
-title: "Service reference"
+title: "Offer module service"
 sidebarTitle: "Service"
-description: "The Offer module service and its methods for working with records directly."
+description: "Resolve the Offer module service and use its generated and custom methods."
 ---
 
-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.
+The Offer module service reads and writes `Offer` and `OfferCondition` rows directly. Use it in subscribers, scheduled jobs, and your own steps when you don’t need what the workflows add on top.
+
+## Resolve the service
+
+Resolve the service from the container with `MercurModules.OFFER`.
 
 ```ts
 import { MercurModules } from "@mercurjs/types"
 
 const offerModuleService = container.resolve(MercurModules.OFFER)
 
-const [offers, count] = await offerModuleService.listAndCountOffers({
-  seller_id: "sel_123",
-})
+const [offers, count] = await offerModuleService.listAndCountOffers(
+  { seller_id: "sel_01JD8Q1234567" },
+  { take: 20 }
+)
 ```
 
+<Warning>
+  The service writes rows only. It doesn’t create prices, inventory items, or links, emit events, or roll back on failure. Use the [workflows](/platform/offer/reference/workflows) for anything that touches pricing, stock, or links.
+</Warning>
+
 ## Generated methods
 
-The `Offer` model gets a standard set of auto-generated methods:
+The service extends `MedusaService({ Offer, OfferCondition })`, which generates these methods for each model:
 
-| Method | Description |
+| Offer | OfferCondition |
 | --- | --- |
-| `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 |
+| `retrieveOffer(id, config?)` | `retrieveOfferCondition(id, config?)` |
+| `listOffers(filters?, config?)` | `listOfferConditions(filters?, config?)` |
+| `listAndCountOffers(filters?, config?)` | `listAndCountOfferConditions(filters?, config?)` |
+| `createOffers(data)` | `createOfferConditions(data)` |
+| `updateOffers(data)` | `updateOfferConditions(data)` |
+| `deleteOffers(ids)` | `deleteOfferConditions(ids)` |
+| `softDeleteOffers(ids)` | `softDeleteOfferConditions(ids)` |
+| `restoreOffers(ids)` | `restoreOfferConditions(ids)` |
 
-## Group by seller
+## listOffers and listAndCountOffers with 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.
+Both offer list methods accept an extra `group_by_seller` filter. Without it they behave like the generated methods.
 
 ```ts
-const [grouped] = await offerModuleService.listAndCountOffers({
-  product_id: "prod_123",
-  group_by_seller: true,
-})
+listOffers(
+  filters?: Record<string, unknown> & { group_by_seller?: boolean },
+  config?: FindConfig<OfferDTO>,
+  sharedContext?: Context
+): Promise<OfferDTO[]>
+
+listAndCountOffers(
+  filters?: Record<string, unknown> & { group_by_seller?: boolean },
+  config?: FindConfig<OfferDTO>,
+  sharedContext?: Context
+): Promise<[OfferDTO[], number]>
 ```
 
-<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>
+With `group_by_seller: true`, the service returns one offer per `(product_id, seller_id)` group, the newest by `created_at`. Each returned offer gets `variant_count` and `offer_ids` for its group, and the count is the number of groups.
+
+Grouped mode reads only the `product_id` and `seller_id` filters. Pagination uses `config.skip` and `config.take`, with `take` defaulting to 20.
+
+## getStatistics
+
+Counts offers, and the distinct stores and products behind them, as they stood at a point in time.
+
+```ts
+getStatistics(
+  input?: OfferStatisticsInput,
+  sharedContext?: Context
+): Promise<OfferStatisticsOutput>
+```
+
+`input.at` defaults to now. `input.filters.seller_id` takes one id or a list. An offer counts when it was created at or before `at` and wasn’t deleted by then.
+
+```ts
+const { offers, sellers, products } =
+  await offerModuleService.getStatistics({ at: new Date("2026-10-01") })
+```
+
+The result is `{ offers, sellers, products }`, each a number.
+
+## Related
+
+- [Offer data models](/platform/offer/reference/data-models)
+- [Offer workflows](/platform/offer/reference/workflows)

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

@@ -1,66 +1,175 @@
 ---
-title: "Workflows"
+title: "Offer workflows"
 sidebarTitle: "Workflows"
-description: "Offer workflows for creating, updating, deleting, and batching inventory."
+description: "Every offer and offer condition workflow, with its input, hooks, and events."
 ---
 
-This reference lists the workflows for the Offer domain. Import them from
-`@mercurjs/core/workflows` and run them against the Medusa container.
+The Offer module ships eight workflows: five for offers and their prices and stock, and three for offer conditions. Import them from `@mercurjs/core/workflows` and run them with the Medusa container.
 
-## Offer workflows
+| Workflow | Id | Emits |
+| --- | --- | --- |
+| `createOffersWorkflow` | `create-offers` | `offer.created` |
+| `updateOffersWorkflow` | `update-offers` | `offer.updated` |
+| `upsertOfferPricesWorkflow` | `upsert-offer-prices` | None |
+| `deleteOffersWorkflow` | `delete-offers` | `offer.deleted` |
+| `batchOfferInventoryItemsWorkflow` | `batch-offer-inventory-items` | `offer.updated` |
+| `createOfferConditionsWorkflow` | `create-offer-conditions` | `offer_condition.created` |
+| `updateOfferConditionsWorkflow` | `update-offer-conditions` | `offer_condition.updated` |
+| `deleteOfferConditionsWorkflow` | `delete-offer-conditions` | `offer_condition.deleted` |
+
+## createOffersWorkflow
 
-| Workflow | Input | Purpose |
+Creates offers with their inventory items, prices, and links. Returns the created `OfferDTO[]`.
+
+| Input | Type | Description |
 | --- | --- | --- |
-| `createOffersWorkflow` | `{ offers[], additional_data? }` | Create offers with prices, inventory, and links |
-| `updateOffersWorkflow` | `{ offers[], updated_by?, 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 |
+| `offers` | `CreateOfferDTO[]` | One entry per offer |
+| `additional_data` | `Record<string, unknown>` | Optional. Passed to `offersCreated` |
+
+Each `CreateOfferDTO` requires `seller_id`, `created_by`, `sku`, `variant_id`, `shipping_profile_id`, `prices`, and at least one `inventory_items` entry. Optional fields are `ean`, `upc`, `manage_inventory`, `allow_backorder`, `leadtime_to_ship`, `condition_id`, and `metadata`.
+
+An `inventory_items` entry takes `required_quantity` (default `1`), `sku`, `title`, and `stock_levels` (`location_id`, `stocked_quantity`). A price takes `amount`, `currency_code`, and optional `min_quantity`, `max_quantity`, and `rules`.
+
+The run creates the inventory items and links them to the offer and to the store of the first entry. It adds prices to each variant’s price set with an `offer_id` rule, creating the price set first if the variant has none. It also links each master product to its first offer’s shipping profile when the product has no profile.
+
+| Hook | Payload |
+| --- | --- |
+| `validate` | `{ input }` |
+| `offersCreated` | `{ offers: OfferDTO[], additional_data }`, each offer with `prices` |
 
-## Hooks
+## updateOffersWorkflow
 
-Each workflow exposes hooks so you can extend it without forking:
+Updates offer rows and, for entries with a `prices` array, replaces that offer’s prices through `upsertOfferPricesWorkflow`. Returns the updated `OfferDTO[]`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `offers` | `UpdateOfferDTO[]` | Keyed by `id`. Every other field is optional |
+| `updated_by` | `string` | Optional. The actor id, passed to both hooks |
+| `additional_data` | `Record<string, unknown>` | Optional. Passed to `offersUpdated` |
 
-| Workflow | Hooks |
+`UpdateOfferDTO` accepts `sku`, `shipping_profile_id`, `manage_inventory`, `allow_backorder`, `leadtime_to_ship`, `condition_id`, `metadata`, and `prices`. Leave out `prices` to keep the current rows. A `condition_id` must point at an active condition.
+
+| Hook | Payload |
 | --- | --- |
-| `createOffersWorkflow` | `validate`, `offersCreated` |
-| `updateOffersWorkflow` | `validate`, `offersUpdated` |
-| `upsertOfferPricesWorkflow` | `offerPricesUpserted` |
-| `deleteOffersWorkflow` | `offersDeleted` |
-| `batchOfferInventoryItemsWorkflow` | `validate`, `offerInventoryItemsBatched` |
+| `validate` | `{ input }` |
+| `offersUpdated` | `{ offers, previous_offers, updated_by, additional_data }` |
+
+`previous_offers` holds the offer rows as they were before the write.
 
-### Hook payloads
+## upsertOfferPricesWorkflow
+
+Replaces each listed offer’s prices without touching other offers on the same variant. Returns `{ offer_id, price_ids }[]` for the prices it created.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `offers` | `{ id, prices: UpsertOfferPriceDTO[] }[]` | The full new price list per offer |
+| `updated_by` | `string` | Optional. Passed to the hook |
+
+A price with an `id` updates that row, a price without one is added, and owned prices left out are deleted with their links. An `id` that belongs to another offer fails the run with `Price … does not belong to offer …`.
 
 | Hook | Payload |
 | --- | --- |
-| `offersCreated` | `{ offers: OfferDTO[], additional_data? }` — each offer carries `created_by` and its `prices` |
-| `offersUpdated` | `{ offers: OfferDTO[], previous_offers: OfferDTO[], updated_by?, additional_data? }` — `previous_offers` is the row state before the write |
-| `offerPricesUpserted` | `{ offers: Array<{ offer_id, previous_prices: OfferPriceDTO[], prices: OfferPriceDTO[], created: string[], updated: string[], deleted: string[] }>, updated_by: string \| null }` |
-| `offersDeleted` | `{ ids: string[], offers: OfferDTO[], additional_data? }` — `offers` is a snapshot taken before deletion, including `prices` |
+| `offerPricesUpserted` | `{ offers, updated_by }`, where `updated_by` is `string \| null` |
 
-`updated_by` is the authenticated actor id. Vendor routes fill it from the session; pass it yourself when running `updateOffersWorkflow` or `upsertOfferPricesWorkflow` directly.
+Each entry in `offers` has these fields:
 
-In `offerPricesUpserted`, `previous_prices` and `prices` are the offer's ladder before and after the write (`amount`, `currency_code`, `min_quantity`, `max_quantity`, `price_rules`). `created` and `deleted` hold the price ids added and removed; `updated` holds the ids rewritten in place whose amount, quantity bounds, or rules actually changed — an unchanged row resent with its id is not listed. The hook also fires when `updateOffersWorkflow` runs the price upsert for you, so a single handler on `upsertOfferPricesWorkflow` covers both entry points. Prices are hard-deleted and Medusa's pricing events carry ids only, so these payloads (and the `offersDeleted` snapshot) are the only place the previous values can be read.
+- **`offer_id`**: the offer
+- **`previous_prices`**: the offer’s prices before the write
+- **`prices`**: the offer’s prices after the write
+- **`created`**: ids of new prices
+- **`updated`**: ids whose amount, currency, quantity bounds, or rules changed; an unchanged row resent with its `id` isn’t listed
+- **`deleted`**: ids of removed prices
 
-```ts
+The hook also fires when `updateOffersWorkflow` runs the upsert, so one handler covers both entry points:
+
+```ts title="src/workflows/hooks/offer-prices-upserted.ts"
 import { upsertOfferPricesWorkflow } from "@mercurjs/core/workflows"
-import { StepResponse } from "@medusajs/framework/workflows-sdk"
 
 upsertOfferPricesWorkflow.hooks.offerPricesUpserted(
   async ({ offers, updated_by }, { container }) => {
-    for (const { offer_id, previous_prices, prices, updated } of offers) {
-      // record a price-history entry for every id in `updated`
+    const logger = container.resolve("logger")
+    for (const { offer_id, updated, deleted } of offers) {
+      logger.info(`${offer_id} by ${updated_by}: ${updated.length} changed`)
+      logger.info(`${offer_id}: ${deleted.length} removed`)
     }
-    return new StepResponse(undefined)
   }
 )
 ```
 
-## Behavior notes
+Deleted prices are gone for good, so this payload is the only place to read their old values.
+
+## deleteOffersWorkflow
+
+Soft-deletes offers. It has no step that removes their prices or inventory items.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `ids` | `string[]` | The offers to delete |
+| `additional_data` | `Record<string, unknown>` | Optional. Passed to `offersDeleted` |
+
+| Hook | Payload |
+| --- | --- |
+| `offersDeleted` | `{ ids, offers, additional_data }` |
+
+`offers` is a snapshot taken before the delete, with each offer’s `prices`.
+
+## batchOfferInventoryItemsWorkflow
+
+Creates, updates, and removes `offer ↔ inventory_item` links on one offer. Returns `{ created, updated, deleted }`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `offer_id` | `string` | The offer to change |
+| `create` | `{ inventory_item_id, required_quantity? }[]` | Optional. Items to link, `required_quantity` defaults to `1` |
+| `update` | `{ inventory_item_id, required_quantity }[]` | Optional. New quantities for linked items |
+| `delete` | `string[]` | Optional. Inventory item ids to unlink |
+| `additional_data` | `Record<string, unknown>` | Optional. Passed to `offerInventoryItemsBatched` |
+
+The run fails when the offer doesn’t exist, an item in `create` doesn’t exist, an item in `delete` isn’t linked, or an id repeats within or across the lists.
+
+| Hook | Payload |
+| --- | --- |
+| `validate` | `{ input }` |
+| `offerInventoryItemsBatched` | `{ offer_id, result, additional_data }` |
+
+## createOfferConditionsWorkflow
+
+Creates offer conditions. Returns `OfferConditionDTO[]`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `offer_conditions` | `CreateOfferConditionDTO[]` | `code` and `label`, plus optional `is_active`, `rank`, and `metadata` |
+
+| Hook | Payload |
+| --- | --- |
+| `offerConditionsCreated` | `{ offer_conditions }` |
+
+## updateOfferConditionsWorkflow
+
+Updates offer conditions by `id`. Returns `OfferConditionDTO[]`.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `offer_conditions` | `UpdateOfferConditionDTO[]` | `id`, plus any of `code`, `label`, `is_active`, `rank`, and `metadata` |
+
+| Hook | Payload |
+| --- | --- |
+| `offerConditionsUpdated` | `{ offer_conditions }` |
+
+## deleteOfferConditionsWorkflow
+
+Soft-deletes offer conditions. The run fails when an id doesn’t exist or when any offer still uses one of the conditions.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `ids` | `string[]` | The conditions to delete |
+
+| Hook | Payload |
+| --- | --- |
+| `offerConditionsDeleted` | `{ ids }` |
 
-- **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.
+## Related
 
-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).
+- [Offer events](/platform/offer/reference/events)
+- [Offer service methods](/platform/offer/reference/service)
+- [Create an offer](/platform/offer/guides/create-an-offer)