Catalog - Product variants
Catalog - Product variants
Catalog - Product variants
The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the Catalog Overview.
A product variant is a version of a product that has its own SKU. For example, a catalog might model a particular style of high-top sneakers that come in both red and blue as one product - high-tops - with two variants - red and blue. From a storefront point of view, product variants are often what shoppers seek. They are also the object that maps to SKUs and tracks inventory. A product with one only variant is a base variant.
A base variant is a virtual projection of the parent product itself, exposed through the Variants API for consistency. When you update a base variant through the Update a product variant or Update variants (batch) endpoint, the changes are applied to the underlying product. Only the following fields are propagated:
sku, price, weight, width, height, depth, is_free_shipping, fixed_cost_shipping_price, cost_price, sale_price, retail_price, upc, mpn, gtin, inventory_level, inventory_warning_level, bin_picking_number, purchasing_disabled, purchasing_disabled_message
For all other product-level data — including images, descriptions, SEO fields, categories, custom fields, and metadata — use the Products API directly.
The Variants API for base variants exists primarily for backward compatibility and integration consistency, exposing only a limited subset of product fields.
When a product has real variants (with options), base variant behavior no longer applies — each variant becomes a first-class entity.
Our Catalog product variants endpoints let you work in two ways.
On a per-product basis, you can create and manage product variants, their images, and their metafields, which are arbitrary key-value attributes.
By design, product variants consist of a combination of product variant option values.
This API family also provides endpoints that can make batch updates to product variants from different products across the Catalog, as well as getting all variants.
The terms “product variant” and “variant” are used interchangeably throughout the documentation.
To learn more about authenticating Catalog endpoints, locate the Authentication section at the top of each endpoint, then click Show Details.
Learn more about Product webhook events.