Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

7.6 KB
Raw Blame
---
title: "Offer workflows"
sidebarTitle: "Workflows"
description: "Every offer and offer condition workflow, with its input, hooks, and events."
---

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:

```ts title="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 }` |

## Related

- [Offer events](/platform/offer/reference/events)
- [Offer service methods](/platform/offer/reference/service)
- [Create an offer](/platform/offer/guides/create-an-offer)