Docs
Catalog API
Product variant options

Catalog - Product variant options

The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the Catalog overview.

Product variant options represent the different facets of a product. For example, size, color, fabric. Variant option values are the actual sizes, colors, fabrics, that are available. Product variants consist of combinations of variant option values.

The following table illustrates the relationship between variant options and variant option values using a line of signature sneakers as an example.

Variant optionsVariant option valuesNo. of variants
size (US Women's)6, 6.5, 7, 7.5, 8, 8.5, 9, 9.5, 10, 10.510
upper materialcanvas, marine plastic, leather3
upper colorbrick, azul, gold3
sole colorcharcoal, white, azul3
270

Our Catalog product variant options endpoints let you work with both variant options and variant option values.

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 Variant Options

GET /catalog/products/{product_id}/options

Request

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

Authentication

  • X-Auth-Token in header

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.

  • page in query - integer

    Specifies the page number in a limited (paginated) list of products.

  • limit in query with default of 50 - integer

    Controls the number of items per page in a limited (paginated) list of products.

  • 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
Get all product options

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals.

example

Create a Product Variant Option

POST /catalog/products/{product_id}/options

Request

Creates a Variant Option.

Required Fields

  • display_name
  • type
  • option_values

Read-Only Fields

  • id

Limits

  • 255 characters option name length.

Notes

  • Only one variant option at a time can be created; individual variant options will contain an array of multiple values.
  • There are several examples listed below that create options, but the SKUs are not updated and they are not a variant on the product. Variant SKUs must be created with a separate request.
  • Variant options will show on the storefront as an option that can be selected by the customer. A request like this could be used to add new choices to a variant that has already been created.
  • If more than one variant needs to be created, use the Create a Product endpoint.

Authentication

  • X-Auth-Token in header

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.

  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json
The model for a POST to create options on a product.

  • product_id    integer

    The unique numerical ID of the product to which the option belongs.

    Example: 4

  • display_name    string

    The name of the option shown on the storefront.

    >= 1 characters<= 255 characters
    Example: Add-a-$5-Donation1535042499-187

  • type    string

    The type of option, which determines how it will display on the storefront. Acceptable values: radio_buttons, rectangles, dropdown, product_list, product_list_with_images, swatch. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch.

    Allowed: radio_buttons | rectangles | dropdown | product_list | product_list_with_images | swatch

  • config    object

    The values for option config can vary based on the Modifier created.

  • sort_order    integer

    Order in which the option is displayed on the storefront.
    Example: 1

  • option_values    array[object]

  • image_url    string

    Publicly available image url

example

Response

Body

object | application/json

  • data    object

    Common Option properties.

  • meta    object

    Empty meta object; may be used later.

example-1

example-2

Get a Product Variant Option

GET /catalog/products/{product_id}/options/{option_id}

Request

Returns a single Variant Option. Optional parameters can be passed in.

Authentication

  • X-Auth-Token in header

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.

  • option_id in path - integer
    required

    The ID of the Option.

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

    Common Option properties.

  • meta    object

    Response metadata.

example

Update a Product Variant Option

PUT /catalog/products/{product_id}/options/{option_id}

Request

Updates a Variant Option.

Read-Only Fields

  • id

Authentication

  • X-Auth-Token in header

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.

  • option_id in path - integer
    required

    The ID of the Option.

  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json
The model for a PUT to update options on a product.

  • id    integer or null

    The unique numerical ID of the option, increments sequentially.

    Example: 55

  • product_id    integer

    The unique numerical ID of the product to which the option belongs.

    Example: 4

  • display_name    string

    The name of the option shown on the storefront.

    >= 1 characters<= 255 characters
    Example: Add-a-$5-Donation1535042499-187

  • type    string

    The type of option, which determines how it will display on the storefront. Acceptable values: radio_buttons, rectangles, dropdown, product_list, product_list_with_images, swatch. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch.

    Allowed: radio_buttons | rectangles | dropdown | product_list | product_list_with_images | swatch

  • config    object

    The values for option config can vary based on the Modifier created.

  • sort_order    integer

    Order in which the option is displayed on the storefront.
    Example: 1

  • option_values    array[object]

  • image_url    string

    Publicly available image url

example

Response

Body

object | application/json

  • data    object

    Common Option properties.

  • meta    object

    Response metadata.

example

Delete a Product Variant Option

DELETE /catalog/products/{product_id}/options/{option_id}

Request

Deletes a Variant Option.

Authentication

  • X-Auth-Token in header

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.

  • option_id in path - integer
    required

    The ID of the Option.

example

Response

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?
Update Variants (Batch)Get All Product Variant Options