Create an offer from your server code

Create an offer with createOffersWorkflow when you list products for a store outside the Vendor panel, for example in a custom route, a seed script, or an import job.

Before you begin

You need these records in place:

A store: its seller_id and the id of a member to record as created_by
A master variant: the variant_id the store will sell
A shipping profile: one that belongs to the store
A stock location: where the starting stock is held

Create the offer

Add a route that runs the workflow

Create an API route that runs createOffersWorkflow with one offer.

src/api/admin/custom/offers/route.ts

import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { createOffersWorkflow } from "@mercurjs/core/workflows"

const stock = [{ location_id: "sloc_01JD8Q1234567", stocked_quantity: 50 }]

export async function POST(req: MedusaRequest, res: MedusaResponse) {
  const { result } = await createOffersWorkflow(req.scope).run({
    input: {
      offers: [
        {
          seller_id: "sel_01JD8Q1234567",
          created_by: "mem_01JD8Q1234567",
          variant_id: "variant_01JD8Q1234567",
          shipping_profile_id: "sp_01JD8Q1234567",
          sku: "ACME-LS-M",
          prices: [{ amount: 4700, currency_code: "eur" }],
          inventory_items: [{ stock_levels: stock }],
        },
      ],
    },
  })

  res.status(201).json({ offer: result[0] })
}

The workflow returns the created Offer rows. The one inventory_items entry becomes a new inventory item with 50 units at the location.

Know what the run wires up

One run does more than insert the row:

Inventory: creates an InventoryItem per entry, links it to the offer with its required_quantity, and links it to the store
Prices: adds each price to the variant’s price set with an offer_id rule and links it to the offer
Barcodes: copies ean and upc from the variant when you leave them out
Shipping: links the master product to the shipping profile if the product has none
Event: emits offer.created with { id, product_id }

Read the offer back with its links

Query the offer with its prices and stock to confirm the result.

const { data: [offer] } = await query.graph({
  entity: "offer",
  fields: [
    "id",
    "sku",
    "prices.amount",
    "prices.currency_code",
    "inventory_item_link.required_quantity",
    "inventory_item_link.inventory_item.location_levels.*",
  ],
  filters: { id: result[0].id },
})

prices reads the offer’s own rows on the shared price set. inventory_item_link returns the pivot rows, so you get required_quantity with each item.

Set selling terms and a condition

The offer accepts optional fields beyond the required ones. Add them to the same entry:

{
  sku: "ACME-LS-M-RF",
  condition_id: "ofcond_01JD8Q1234567",
  manage_inventory: true,
  allow_backorder: false,
  leadtime_to_ship: 3,
  metadata: { source: "erp" },
}

condition_id must point at an active offer condition. manage_inventory defaults to true, allow_backorder to false, and leadtime_to_ship to null.

Attach custom data with additional_data

Pass additional_data to the run to hand extra values to the offersCreated hook. Use it to store data from your own module next to the offer.

src/workflows/hooks/offers-created.ts

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

createOffersWorkflow.hooks.offersCreated(
  async ({ offers, additional_data }, { container }) => {
    const logger = container.resolve("logger")
    for (const offer of offers) {
      logger.info(`${offer.sku}: ${additional_data?.source ?? "api"}`)
    }
  }
)

The hook receives the created offers with their prices loaded. Run the workflow with additional_data: { source: "erp" } to see the value in the handler.

Handle a failed run

The workflow validates the whole input and rolls back on failure. Compensation removes the inventory items, prices, and links it already created. A run fails when:

A variant doesn’t exist: Variant with id … was not found
An offer has no inventory items: Offer must have at least one inventory item
A condition is unknown or inactive: Offer condition … is not active or not found
A SKU is taken in the store: the (seller_id, sku) unique index rejects the insert

Store

Catalog

Offer

Attribute

Product Edit

Order Group

Commission

Payout

Review

Before you begin

Create the offer

Set selling terms and a condition

Attach custom data with additional_data

Handle a failed run

Next steps

​Before you begin

​Create the offer

​Set selling terms and a condition

​Attach custom data with additional_data

​Handle a failed run

​Next steps

Before you begin

Create the offer

Set selling terms and a condition

Attach custom data with additional_data

Handle a failed run

Next steps