> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mercurjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Create Master Products and Offers

> Publish one master product, add two competing seller offers, and read per-offer prices from the Store API.

Mercur runs a master catalog. One canonical product record holds many sellers listing against it. The product defines what the item is. Each seller's offer defines how they sell it: their SKU, price, stock, and shipping. This tutorial builds the classic buy-box scenario: two sellers, one product, two competing offers.

<Info>
  No seller owns a product. There is no owner column. Creating a product adds a candidate to the shared catalog. The creator gets attribution, so their unpublished submissions appear in their own list, but no rights over the record after publication. What looks like ownership elsewhere is split into three things: selling eligibility, creator attribution, and the status lifecycle. See [Products](/rc/learn/products).
</Info>

## What you'll build

You end with a published master product carrying offers from two sellers at different prices. Both offers are visible side by side through the Store API, each with its own calculated price.

## Product vs offer

Three concerns live in three places. Keep them separate as you build.

| Concern               | Lives on                   | Example                                             |
| --------------------- | -------------------------- | --------------------------------------------------- |
| What the item is      | Master product             | "Classic White T-Shirt", variants, attributes       |
| Who may sell it       | `product_seller` allowlist | Empty = every seller; assigned = only those sellers |
| How a seller sells it | Offer                      | SKU, price, stock, shipping profile                 |

## Build the buy box

<Steps>
  <Step title="Publish a master product">
    As Seller A, create a product in the Vendor Portal, such as "Classic White T-Shirt" with a size variant. It enters as `proposed`. As the operator, confirm it in the Admin Panel so it becomes `published`. The review flow is covered by the [Product Edit](/platform/product-edit/overview) module.

    The published product now belongs to the shared catalog. Note what it does not have: a seller price or seller stock.
  </Step>

  <Step title="Create Seller A's offer">
    In Seller A's Vendor Portal, create an offer against the product's variant. Give it their own SKU, a price of \$25, stock of 100, and one of their shipping profiles.

    <Warning>
      Offer inventory links to the offer, not the variant. Each seller manages stock for their own listing independently. A variant has no marketplace-wide stock figure, and its own `inventory_items` relation is empty for offer-based listings. Always read stock through the offer.
    </Warning>
  </Step>

  <Step title="List the same product as Seller B">
    As Seller B, find the same published product in the catalog and create a competing offer on the same variant: a different SKU, \$23, stock of 40. The `(seller_id, sku)` pair is unique per seller, so both sellers can use whatever SKU scheme they like.

    Nothing about the master product changed. Two commercial listings now point at one catalog entry.
  </Step>

  <Step title="Read the buy box from the Store API">
    The Store API exposes offers directly, each with its own calculated price. Fetch them by product id:

    ```bash Terminal theme={null}
    curl "http://localhost:9000/store/offers?product_id=prod_123" \
      -H "x-publishable-api-key: <key>"
    ```

    Offers share the variant's price set scoped by an offer rule. Each offer carries its own prices without duplicating the variant, and the storefront computes a `calculated_price` per offer. A buy-box storefront fetches the product once, then renders every seller's offer against it.
  </Step>

  <Step title="Check out against an offer">
    Add Seller B's offer to a cart and place the order. The cart line item links to the specific offer purchased, and that link is preserved onto the order line item. Fulfillment, [commission calculation](/rc/learn/commissions), and [payouts](/rc/learn/payouts) all resolve to Seller B, even though both sellers list the same variant.
  </Step>
</Steps>

## Verify

Confirm the buy box behaves as expected.

1. Both offers appear in `GET /store/offers?product_id=...` with different `calculated_price` values.
2. Each seller's Vendor Portal shows only their own offer. The Admin Panel lists both with store, pricing, and inventory.
3. After the checkout in step 5, the order lands with Seller B. Seller A's offer and stock are untouched.
4. Reducing Seller B's offer stock does not affect Seller A's availability. Inventory is per offer.

## FAQ

<AccordionGroup>
  <Accordion title="How do I restrict who may sell a product?">
    The operator manages the `product_seller` allowlist. A product with assignments is visible and sellable only for those sellers, while a product with no assignments is open to every seller. Eligibility limits selling. It does not limit who may propose edits to the shared record.
  </Accordion>

  <Accordion title="Can two sellers use the same SKU?">
    Yes. SKU uniqueness is per seller (`seller_id` + `sku`). Seller A and Seller B can both use `TSHIRT-WHITE-M`. A single seller cannot list the same SKU twice.
  </Accordion>

  <Accordion title="Who fulfills, refunds, and gets paid when several sellers list the same variant?">
    Always the seller whose offer was purchased. The offer link travels from cart line to order line, so fulfillment, returns, commission, and payout all resolve through it. The variant alone is never enough to identify the seller.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Offers" href="/rc/learn/offers">
    The offer data model, relationships, and checkout links.
  </Card>

  <Card title="Order Groups" href="/rc/learn/order-groups">
    What happens when a cart spans both sellers: the multi-vendor split.
  </Card>
</CardGroup>