Offer workflows

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.

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

Creates offers with their inventory items, prices, and links. Returns the created OfferDTO[].

Input	Type	Description
`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`

updateOffersWorkflow

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`

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
`validate`	`{ input }`
`offersUpdated`	`{ offers, previous_offers, updated_by, additional_data }`

previous_offers holds the offer rows as they were before the write.

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
`offerPricesUpserted`	`{ offers, updated_by }`, where `updated_by` is `string \| null`

Each entry in offers has these fields:

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

The hook also fires when updateOffersWorkflow runs the upsert, so one handler covers both entry points:

src/workflows/hooks/offer-prices-upserted.ts

import { upsertOfferPricesWorkflow } from "@mercurjs/core/workflows"

upsertOfferPricesWorkflow.hooks.offerPricesUpserted(
  async ({ offers, updated_by }, { container }) => {
    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`)
    }
  }
)

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 }`

Store

Catalog

Offer

Attribute

Product Edit

Order Group

Commission

Payout

Review

createOffersWorkflow

updateOffersWorkflow

upsertOfferPricesWorkflow

deleteOffersWorkflow

batchOfferInventoryItemsWorkflow

createOfferConditionsWorkflow

updateOfferConditionsWorkflow

deleteOfferConditionsWorkflow

​createOffersWorkflow

​updateOffersWorkflow

​upsertOfferPricesWorkflow

​deleteOffersWorkflow

​batchOfferInventoryItemsWorkflow

​createOfferConditionsWorkflow

​updateOfferConditionsWorkflow

​deleteOfferConditionsWorkflow

​Related

createOffersWorkflow

updateOffersWorkflow

upsertOfferPricesWorkflow

deleteOffersWorkflow

batchOfferInventoryItemsWorkflow

createOfferConditionsWorkflow

updateOfferConditionsWorkflow

deleteOfferConditionsWorkflow

Related