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

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

  • include_fields in query - string

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

  • exclude_fields in query - string

    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

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

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

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

    • option_id in path - integer - required

      The ID of the Option.

    • include_fields in query - string

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

    • exclude_fields in query - string

      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

    object | application/json
    • data

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

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

      • option_id in path - integer - required

        The ID of the Option.

      example

      Response

      Did you find what you were looking for?