Skip to main content
Use offers to let several stores sell the same catalog product, each on its own terms. Products in Mercur live in one shared master catalog that no store owns. An offer is the record that connects a store to one master variant. It carries everything that makes the listing the store’s own: its SKU, price, inventory, condition, and shipping profile. The Offer module holds the offer and its conditions, and links reach out to the store, the catalog, pricing, inventory, fulfillment, and the cart and order line items that buy it. The Linen shirt master product sits behind an Offers list for its M variant: ACME, GLOBEX, and INITECH each list the same variant with their own SKU, condition, price, and stock. The Linen shirt master product sits behind an Offers list for its M variant: ACME, GLOBEX, and INITECH each list the same variant with their own SKU, condition, price, and stock.
The data model is Offer (id prefix offer), resolved with MercurModules.OFFER from @mercurjs/types. A store never owns a product. Two stores selling the same variant each hold their own offer.

​
Key features

The Offer module covers everything a store needs to sell a catalog variant:
  • Per-store listings: an offer points at one master variant, with a SKU that’s unique within its store
  • Offer-scoped pricing: price rows sit on the variant’s shared price set, each tagged with an offer_id price rule
  • Offer-scoped inventory: inventory items link to the offer, not the variant, so stock never mixes between stores
  • Conditions: operators define conditions such as new or refurbished, and stores list offers under the active ones
  • Per-offer shipping: each offer names the store’s own shipping profile
  • Order attribution: cart and order line items link to the offer that was bought
  • Hooks and events: every workflow exposes hooks and emits offer.* events for your own side effects

​
How it works

An offer moves through the marketplace in four steps:
  1. A store runs createOffersWorkflow against a master variant, with a SKU, prices, inventory items, and a shipping profile.
  2. The workflow writes the prices onto the variant’s price set with an offer_id rule and creates inventory items linked to the offer.
  3. When a shopper adds the offer to a cart, the line item links to the offer and pricing resolves the offer’s own rows.
  4. At checkout the order line item keeps the offer link, so the right store fulfills the item and gets paid.

​
Get started

Learn how offers, prices, stock, and shipping fit together.

What is an offer

The offer record, its SKU rules, and offer conditions.

Pricing & inventory

Prices on the shared price set and stock linked to the offer.

Shipping

How an offer ships with its store’s shipping profile.

​
Examples

Build against offers in your own server code.

Create an offer

Run createOffersWorkflow from an API route.

Bulk-create offers

List a store’s catalog in a single run.

Manage offer inventory

Attach, update, and detach inventory items on an offer.

​
Resources

The data models, links, workflows, service methods, and events behind offers.

Data models

Offer and OfferCondition, field by field.

Links

How offers link to stores, catalog, pricing, inventory, and orders.

Workflows

Offer, price, inventory, and condition workflows with their hooks.

Service

Module service methods for reading and writing records directly.

Events

Events emitted as offers and conditions change.