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
  • include_fields in query - array

    Fields to include, in a comma-separated list. The ID and the specified fields will be returned.

    Type: array[string]

  • 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.

    Type: array[string]

  • 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

object | application/json
  • data
    array[object]

  • 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.

Authentication

  • X-Auth-Token in header
    required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string
    required

    The MIME type of the request body.

Body

application/json

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

  • cost_price
    number 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.

  • price
    number 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’s price field) will be used as the base price.

  • sale_price
    number 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_price
    number 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.

  • weight
    number 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.

  • width
    number 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ʼs width field) will be used as the base width.

  • height
    number 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ʼs height field) will be used as the base height.

  • depth
    number 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ʼs depth field) will be used as the base depth.

  • is_free_shipping
    boolean

    Flag used to indicate whether the variant has free shipping. If true, the shipping cost for the variant will be zero.

  • fixed_cost_shipping_price
    number 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_disabled
    boolean

    If true, this variant will not be purchasable on the storefront.

  • purchasing_disabled_message
    string

    If purchasing_disabled is true, this message should show on the storefront when the variant is selected.

    >= 0 characters<= 255 characters
  • upc
    string or null

    The UPC code used in feeds for shopping comparison sites and external channel integrations.

  • inventory_level
    integer 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.

    Max: 2147483647
  • inventory_warning_level
    integer or null

    When the variant hits this inventory level, it is considered low stock.

    Max: 2147483647
  • bin_picking_number
    string or null

    Identifies where in a warehouse the variant is located.

    >= 0 characters<= 255 characters
  • image_url
    string

    Publicly available image url

  • gtin
    string

    Global Trade Item Number

    Example: 012345678905

  • mpn
    string

    Manufacturer Part Number

    Example: HV-HM02

  • product_id
    integer

  • sku
    string

    >= 1 characters<= 255 characters
  • option_values
    array[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

    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
    • include_fields in query - array

      Fields to include, in a comma-separated list. The ID and the specified fields will be returned.

      Type: array[string]

    • 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.

      Type: array[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
    • Content-Type in header with default of application/json - string
      required

      The MIME type of the request body.

    Body

    application/json

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

    • cost_price
      number 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.

    • price
      number 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’s price field) will be used as the base price.

    • sale_price
      number 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_price
      number 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.

    • weight
      number 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.

    • width
      number 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ʼs width field) will be used as the base width.

    • height
      number 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ʼs height field) will be used as the base height.

    • depth
      number 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ʼs depth field) will be used as the base depth.

    • is_free_shipping
      boolean

      Flag used to indicate whether the variant has free shipping. If true, the shipping cost for the variant will be zero.

    • fixed_cost_shipping_price
      number 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_disabled
      boolean

      If true, this variant will not be purchasable on the storefront.

    • purchasing_disabled_message
      string

      If purchasing_disabled is true, this message should show on the storefront when the variant is selected.

      >= 0 characters<= 255 characters
    • upc
      string or null

      The UPC code used in feeds for shopping comparison sites and external channel integrations.

    • image_url
      string

      Publicly available image url

    • inventory_level
      integer 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.

      Max: 2147483647
    • inventory_warning_level
      integer or null

      When the variant hits this inventory level, it is considered low stock.

      Max: 2147483647
    • bin_picking_number
      string or null

      Identifies where in a warehouse the variant is located.

      >= 0 characters<= 255 characters
    • mpn
      string

      The Manufacturer Part Number (MPN) for the variant.

    • gtin
      string

      Example: 012345678905

    • product_id
      integer

    • sku
      string

      >= 1 characters<= 255 characters

      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
      • Accept in header with default of application/json - string
        required

        The MIME type of the response body.

      • product_id in path - integer
        required

        The ID of the Product to which the resource belongs. Product variant metafield endpoints that have the product_id in the request path are successful as long as the parameter is not empty. The product_id segment is there only for path consistency.

      • variant_id in path - integer
        required

        ID of the variant on a product, or on an associated Price List Record.

      example

      Response

      Did you find what you were looking for?