Offer module links

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`	Writable, many offers to one store, table `offer_seller`	`offer-seller-link.ts`
Offer to product	`Product`	Writable, many offers to one product, table `offer_product`	`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 offer row keeps seller_id for filters and the unique SKU index, and the offer_seller link table mirrors it so the Medusa index engine can join offers to stores. createOffersWorkflow writes both; set seller_id and let the workflow create the link.

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. The product link is a writable offer_product table, mirrored from offer.product_id by createOffersWorkflow, so the index engine can filter offers by product status. The variant link is read-only and reads offer.variant_id.

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.

const { data: offers } = await query.graph({
  entity: "offer",
  fields: ["id", "shipping_profile.id", "shipping_profile.name"],
})

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.

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",
  ],
})

Every row returned also carries an offer_id price rule with the offer’s id.

Offer to inventory item

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. The link has three aliases:

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

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.

const { data: [cart] } = await query.graph({
  entity: "cart",
  fields: ["items.id", "items.offer.id", "items.offer.seller_id"],
  filters: { id: "cart_01JD8Q1234567" },
})

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.

Product to shipping profile

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.

Store

Catalog

Offer

Attribute

Product Edit

Order Group

Commission

Payout

Review

Offer to store

Offer to product and variant

Offer to shipping profile

Offer to price

Offer to inventory item

Cart and order line items to offer

Product to shipping profile

​Offer to store

​Offer to product and variant

​Offer to shipping profile

​Offer to price

​Offer to inventory item

​Cart and order line items to offer

​Product to shipping profile

Offer to store

Offer to product and variant

Offer to shipping profile

Offer to price

Offer to inventory item

Cart and order line items to offer

Product to shipping profile