Docs
Catalog API
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.

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 /catalog/products/{product_id}/variants

Request

Returns a list of product variants. Optional parameters can be passed in.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string

example

Response

Body

object | application/json

  • data    array[]

  • meta    object

    Data about the response, including pagination and collection totals.

example

Create a product variant

POST /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. To obtain the option_values to include in this request, use the Create a product variant option endpoint.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string

Body

application/json

The model for a POST to create variants on a product.

example

Response

Body

object | application/json

  • data

  • meta    object

    Response metadata.

example-1

example-2

Get a product variant

GET /catalog/products/{product_id}/variants/{variant_id}

Request

Returns a single product variant. Optional parameters can be passed in.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string

example

Response

Body

object | application/json

  • data

  • meta    object

    Response metadata.

example

Update a product variant

PUT /catalog/products/{product_id}/variants/{variant_id}

Request

Updates a product variant.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string

Body

application/json

The model for a PUT to update variants on a product.

example

Response

Body

object | application/json

  • data

  • meta    object

    Response metadata.

example

Delete a product variant

DELETE /catalog/products/{product_id}/variants/{variant_id}

Request

Deletes a product variant.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string

example

Response

Did you find what you were looking for?
Delete product modifier valueGet all product variants