Products, variants, variant groups, prices, and stock
Learn the difference between a product, a purchasable variant, a variant group, and context-shaped price and stock before choosing API, Search, or storefront docs.
Start here when catalog, storefront, Search, price, stock, or MCP work depends on the difference between product, variant group, variant, price, and stock.
These records share catalog context, but they do different jobs. Choose the owner first, then open the matching reference for exact fields, limits, status codes, and request shapes.
Choose the right surface
| Job | Use | Why |
|---|---|---|
| Change the shopper-recognizable item | Products reference | Product records own the item people recognize, plus product relationships, images, duplication, and delete behavior. |
| Define product choice dimensions | Variant Templates reference | Templates define the attribute dimensions a product can group variants by. |
| Manage a choice group | Variant Groups reference | Variant groups own grouped presentation, media, tags, slugs, and channel status. |
| Change a sellable version | Variants reference | Variants own purchasable versions, base prices, warehouse stock, dimensions, and shipping attributes. |
| Override pricing for buyer context | Customer groups and pricing | Customer-group prices override normal variant prices for specific account contexts. |
| Build listing, search, facets, or autocomplete | Search latest | Search GraphQL is the preferred storefront discovery surface. |
Product and variant in plain English
A product is the item a customer recognizes: the running shoe, black hoodie, or ceramic mug.
A variant is the exact version the customer can buy: size 42, black, 500 ml, or digital edition.
A customer does not buy an abstract product. They buy one variant of that product.
Where variant groups fit
A variant group sits between the whole product and one exact variant. Use it when related variants should share a shopper choice or presentation layer.
For example, a table product might group variants by material and finish, while each exact size remains a purchasable variant. The group can own media, tags, translations, channel status, and other presentation details without moving those details onto every variant.
Variant groups depend on the product's variant-template dimensions. If a group is deleted, its variants detach from the group; the variants are not deleted by that group delete.
For a deeper group-specific model, read Variant groups. For exact operations, use Variant Groups reference.
Where prices fit
Price belongs to the selling context around a variant. The same recognizable product can show different prices by:
- consumer versus business selling experience.
- market, currency, or tax context.
- tax, currency, or regional pricing expectations.
- campaign or sale state.
Base variant pricing belongs under Variants because the current model scopes a base price to one variant, one store group, and one market. Customer-group pricing is separate: use it only when an account context should override the normal variant price.
For exact price fields, sale behavior, bulk limits, and response shapes, use the Variants reference.
Where stock fits
Stock belongs to the variant and warehouse context, not to the product name. Availability can differ when:
- one warehouse has units available and another does not.
- one region can sell now while another is out of stock.
- one pickup or delivery context can promise inventory that another cannot.
Management stock routes create, update, adjust, or delete stock rows between variants and warehouses. Search availability for flexible products should respect the active variant-group scope; stock from a sibling color, finish, material, or size group should not make the current group look available.
For exact stock write behavior, delta semantics, bulk limits, partial-success responses, and MCP approval behavior, use the Variants reference and MCP server.
Where to go next
- Need REST route selection? Start with APIs, then choose Management API or Shopper API.
- Need to decide whether variant groups are the right model? Read Variant groups, then use the Variant Groups reference for exact operations.
- Building storefront discovery, listing, autocomplete, or facets? Start with Search latest.
- Building product UI? Start with React SDK latest, then see Product detail page or Product listing and search.
- Working with product images or assets? Start with Media.