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.
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.
Resources
Webhooks
Learn more about Product webhook events.
Additional Catalog endpoints
Get all product variants
GET /stores/{store_hash}/v3/catalog/products/{product_id}/variants
Request
Returns a list of product variants. Optional parameters can be passed in.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- include_fields in query - array
Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
- exclude_fields in query - array
Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
- page in query - integer
Specifies the page number in a limited (paginated) list of products.
- limit in query - integer
Controls the number of items per page in a limited (paginated) list of products.
example
Response
Body
dataarray[object]
metaobject
Data about the response, including pagination and collection totals.
example
Create a product variant
POST /stores/{store_hash}/v3/catalog/products/{product_id}/variants
Request
Creates a product variant.
Required Fields
- sku
- option_values
Read-Only Fields
- id
Limits
- 600 SKUs per product limit.
- 255 characters SKU length limit.
Variants need to be created one at a time using this endpoint. To use a variant array, create products, and variants in the same call use the Create Products endpoint during the initial product creation.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- Content-Type in header with default of application/json - stringrequired
The MIME type of the request body.
Body
The model for a POST to create variants on a product.
cost_pricenumber or null
The cost price of the variant. It is not affected by Price List prices. This value displays as null in the control panel when
cost_price
equals zero.pricenumber or null
This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is
null
, the product’s default price (set in the Product resource’sprice
field) will be used as the base price.sale_pricenumber or null
This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s
price
field) will be used as the sale price.retail_pricenumber or null
This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s
price
field) will be used as the retail price.weightnumber or null
This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.
widthnumber or null
Width of the variant, which can be used when calculating shipping costs. If this value is
null
, the productʼs default width (set in the Product resourceʼswidth
field) will be used as the base width.heightnumber or null
Height of the variant, which can be used when calculating shipping costs. If this value is
null
, the productʼs default height (set in the Product resourceʼsheight
field) will be used as the base height.depthnumber or null
Depth of the variant, which can be used when calculating shipping costs. If this value is
null
, the productʼs default depth (set in the Product resourceʼsdepth
field) will be used as the base depth.is_free_shippingboolean
Flag used to indicate whether the variant has free shipping. If
true
, the shipping cost for the variant will be zero.fixed_cost_shipping_pricenumber or null
A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.
purchasing_disabledboolean
If
true
, this variant will not be purchasable on the storefront.purchasing_disabled_messagestring
>= 0 characters<= 255 charactersIf
purchasing_disabled
istrue
, this message should show on the storefront when the variant is selected.upcstring or null
The UPC code used in feeds for shopping comparison sites and external channel integrations.
inventory_levelinteger or null
Inventory level for the variant, which is used when the product’s inventory_tracking is set to
variant
. The Catalog API returns the inventory for only the default location.The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories, or the total inventory for a product, cannot exceed 2,147,483,647.
If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit.
The Catalog API handles limits in a different way than the Inventory API. For more information, see Limit handling.
inventory_warning_levelinteger or null
When the variant hits this inventory level, it is considered low stock.
bin_picking_numberstring or null
>= 0 characters<= 255 charactersIdentifies where in a warehouse the variant is located.
image_urlstring
Publicly available image url
gtinstring
Global Trade Item Number
Example: 012345678905
mpnstring
Manufacturer Part Number
Example: HV-HM02
product_idinteger
skustring
>= 1 characters<= 255 charactersoption_valuesarray[object]
Array of option and option values IDs that make up this variant. Will be empty if the variant is the productʼs base variant.
example
Response
Body
data
metaobject
Response metadata.
example-1
example-2
Get a product variant
GET /stores/{store_hash}/v3/catalog/products/{product_id}/variants/{variant_id}
Request
Returns a single product variant. Optional parameters can be passed in.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- include_fields in query - array
Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
- exclude_fields in query - array
Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
example
Response
Body
data
metaobject
Response metadata.
example
Update a product variant
PUT /stores/{store_hash}/v3/catalog/products/{product_id}/variants/{variant_id}
Request
Updates a product variant.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- Content-Type in header with default of application/json - stringrequired
The MIME type of the request body.
Body
The model for a PUT to update variants on a product.
cost_pricenumber or null
The cost price of the variant. It is not affected by Price List prices. This value displays as null in the control panel when
cost_price
equals zero.pricenumber or null
This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is
null
, the product’s default price (set in the Product resource’sprice
field) will be used as the base price.sale_pricenumber or null
This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s
price
field) will be used as the sale price.retail_pricenumber or null
This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s
price
field) will be used as the retail price.weightnumber or null
This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.
widthnumber or null
Width of the variant, which can be used when calculating shipping costs. If this value is
null
, the productʼs default width (set in the Product resourceʼswidth
field) will be used as the base width.heightnumber or null
Height of the variant, which can be used when calculating shipping costs. If this value is
null
, the productʼs default height (set in the Product resourceʼsheight
field) will be used as the base height.depthnumber or null
Depth of the variant, which can be used when calculating shipping costs. If this value is
null
, the productʼs default depth (set in the Product resourceʼsdepth
field) will be used as the base depth.is_free_shippingboolean
Flag used to indicate whether the variant has free shipping. If
true
, the shipping cost for the variant will be zero.fixed_cost_shipping_pricenumber or null
A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.
purchasing_disabledboolean
If
true
, this variant will not be purchasable on the storefront.purchasing_disabled_messagestring
>= 0 characters<= 255 charactersIf
purchasing_disabled
istrue
, this message should show on the storefront when the variant is selected.upcstring or null
The UPC code used in feeds for shopping comparison sites and external channel integrations.
inventory_levelinteger or null
Inventory level for the variant, which is used when the product’s inventory_tracking is set to
variant
. The Catalog API returns the inventory for only the default location.The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories, or the total inventory for a product, cannot exceed 2,147,483,647.
If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit.
The Catalog API handles limits in a different way than the Inventory API. For more information, see Limit handling.
inventory_warning_levelinteger or null
When the variant hits this inventory level, it is considered low stock.
bin_picking_numberstring or null
>= 0 characters<= 255 charactersIdentifies where in a warehouse the variant is located.
mpnstring
The Manufacturer Part Number (MPN) for the variant.
gtinstring
Example: 012345678905
product_idinteger
skustring
>= 1 characters<= 255 characters
example
Response
Body
data
metaobject
Response metadata.
example
Delete a product variant
DELETE /stores/{store_hash}/v3/catalog/products/{product_id}/variants/{variant_id}
Request
Deletes a product variant.
Authentication
- X-Auth-Token in headerrequired
Parameters
- store_hash in path - string
- Accept in header with default of application/json - stringrequired
The MIME type of the response body.
- product_id in path - integerrequired
The ID of the
Product
to which the resource belongs. Product variant metafield endpoints that have theproduct_id
in the request path are successful as long as the parameter is not empty. Theproduct_id
segment is there only for path consistency. - variant_id in path - integerrequired
ID of the variant on a product, or on an associated Price List Record.