Product Variant Options | BigCommerce Dev Center

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 options	Variant option values	No. of variants
size (US Women's)	6, 6.5, 7, 7.5, 8, 8.5, 9, 9.5, 10, 10.5	10
upper material	canvas, marine plastic, leather	3
upper color	brick, azul, gold	3
sole color	charcoal, white, azul	3
		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 https://api.bigcommerce.com/stores/{store_hash}/v3/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

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/products/[product_id]/options' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

Get all product options

dataarray[object]
metaobject
Data about the response, including pagination and collection totals.

example

{
  "data": [
    {
      "id": 55,
      "product_id": 4,
      "display_name": "Add-a-$5-Donation1535042499-187",
      "type": "radio_buttons",
      "config": {
        "default_value": "string",
        "checked_by_default": true,
        "checkbox_label": "string",
        "date_limited": true,
        "date_limit_mode": "range",
        "date_earliest_value": "2019-08-24",
        "date_latest_value": "2019-08-24",
        "file_types_mode": "specific",
        "file_types_supported": [
          "images, documents, other"
        ],
        "file_types_other": [
          "pdf"
        ],
        "file_max_size": 5,
        "text_characters_limited": true,
        "text_min_length": 1,
        "text_max_length": 55,
        "text_lines_limited": true,
        "text_max_lines": 4,
        "number_limited": true,
        "number_limit_mode": "lowest",
        "number_lowest_value": 100,
        "number_highest_value": 0,
        "number_integers_only": false,
        "product_list_adjusts_inventory": true,
        "product_list_adjusts_pricing": true,
        "product_list_shipping_calc": "weight"
      },
      "sort_order": 1,
      "option_values": [
        {
          "is_default": false,
          "label": "Green",
          "sort_order": 0,
          "value_data": {},
          "id": 0
        }
      ],
      "name": "Add-a-$5-Donation1535042499-187"
    }
  ],
  "meta": {
    "pagination": {
      "total": 36,
      "count": 36,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "previous": "string",
        "current": "?page=1&limit=50",
        "next": "string"
      }
    }
  }
}

Create a Product Variant Option

POST https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/options

Request

Creates a Variant Option.

Required Fields

display_name
type
option_values

Read-Only Fields

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_idinteger
The unique numerical ID of the product to which the option belongs.
Example: 4
display_namestring
The name of the option shown on the storefront.
>= 1 characters<= 255 characters
Example: Add-a-$5-Donation1535042499-187
typestring
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
configobject
The values for option config can vary based on the Modifier created.
sort_orderinteger
Order in which the option is displayed on the storefront.
Example: 1
option_valuesarray[object]
image_urlstring
Publicly available image url

example

{
  "product_id": 4,
  "display_name": "Add-a-$5-Donation1535042499-187",
  "type": "radio_buttons",
  "config": {
    "default_value": "string",
    "checked_by_default": true,
    "checkbox_label": "string",
    "date_limited": true,
    "date_limit_mode": "range",
    "date_earliest_value": "2018-08-31T00:00:00+00:00",
    "date_latest_value": "2019-01-01T00:00:00+00:00",
    "file_types_mode": "specific",
    "file_types_supported": [
      "images",
      "documents",
      "other"
    ],
    "file_types_other": [
      "pdf",
      "txt"
    ],
    "file_max_size": 5,
    "text_characters_limited": true,
    "text_min_length": 1,
    "text_max_length": 55,
    "text_lines_limited": true,
    "text_max_lines": 4,
    "number_limited": true,
    "number_limit_mode": "lowest",
    "number_lowest_value": 100,
    "number_highest_value": 0,
    "number_integers_only": false,
    "product_list_adjusts_inventory": true,
    "product_list_adjusts_pricing": true,
    "product_list_shipping_calc": "weight"
  },
  "sort_order": 1,
  "option_values": [
    {
      "is_default": false,
      "label": "Green",
      "sort_order": 0,
      "value_data": {},
      "id": 0
    }
  ],
  "image_url": "string"
}

Response

Body

object | application/json

dataobject
metaobject
Empty meta object; may be used later.

example-1

{
  "data": {
    "id": 55,
    "product_id": 4,
    "display_name": "Add-a-$5-Donation1535042499-187",
    "type": "radio_buttons",
    "config": {
      "default_value": "string",
      "checked_by_default": true,
      "checkbox_label": "string",
      "date_limited": true,
      "date_limit_mode": "earliest",
      "date_earliest_value": "2022-08-24T00:00:00+00:00",
      "date_latest_value": "2022-08-27T00:00:00+00:00",
      "file_types_mode": "specific",
      "file_types_supported": [
        "images, documents, other"
      ],
      "file_types_other": [
        "pdf"
      ],
      "file_max_size": 5,
      "text_characters_limited": true,
      "text_min_length": 1,
      "text_max_length": 55,
      "text_lines_limited": true,
      "text_max_lines": 4,
      "number_limited": true,
      "number_limit_mode": "lowest",
      "number_lowest_value": 100,
      "number_highest_value": 0,
      "number_integers_only": false,
      "product_list_adjusts_inventory": true,
      "product_list_adjusts_pricing": true,
      "product_list_shipping_calc": "none"
    },
    "sort_order": 1,
    "option_values": [
      {
        "is_default": false,
        "label": "Green",
        "sort_order": 0,
        "value_data": {},
        "id": 0
      }
    ],
    "image_url": "string",
    "name": "Add-a-$5-Donation1535042499-187"
  },
  "meta": {}
}

example-2

{
  "data": {
    "id": 220,
    "product_id": 192,
    "name": "Color (Colors only)",
    "display_name": "Color",
    "type": "swatch",
    "sort_order": 0,
    "option_values": [
      {
        "id": 174,
        "label": "Beige",
        "sort_order": 1,
        "value_data": {
          "colors": [
            "#FAFAEB"
          ]
        },
        "is_default": false
      },
      {
        "id": 175,
        "label": "Grey",
        "sort_order": 2,
        "value_data": {
          "colors": [
            "#BDBDBD"
          ]
        },
        "is_default": false
      },
      {
        "id": 176,
        "label": "Black",
        "sort_order": 3,
        "value_data": {
          "colors": [
            "#000000"
          ]
        },
        "is_default": false
      },
      {
        "id": 189,
        "label": "Black-Walnut",
        "sort_order": 4,
        "value_data": {
          "colors": [
            "#e80ee8"
          ]
        },
        "is_default": false
      }
    ],
    "config": {}
  },
  "meta": {}
}

Get a Product Variant Option

GET https://api.bigcommerce.com/stores/{store_hash}/v3/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.
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

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/products/[product_id]/options/[option_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

data
metaobject
Response metadata.

example

{
  "data": {
    "id": 55,
    "product_id": 4,
    "display_name": "Add-a-$5-Donation1535042499-187",
    "type": "radio_buttons",
    "config": {
      "default_value": "string",
      "checked_by_default": true,
      "checkbox_label": "string",
      "date_limited": true,
      "date_limit_mode": "range",
      "date_earliest_value": "2019-08-24",
      "date_latest_value": "2019-08-24",
      "file_types_mode": "specific",
      "file_types_supported": [
        "images, documents, other"
      ],
      "file_types_other": [
        "pdf"
      ],
      "file_max_size": 5,
      "text_characters_limited": true,
      "text_min_length": 1,
      "text_max_length": 55,
      "text_lines_limited": true,
      "text_max_lines": 4,
      "number_limited": true,
      "number_limit_mode": "lowest",
      "number_lowest_value": 100,
      "number_highest_value": 0,
      "number_integers_only": false,
      "product_list_adjusts_inventory": true,
      "product_list_adjusts_pricing": true,
      "product_list_shipping_calc": "weight"
    },
    "sort_order": 1,
    "option_values": [
      {
        "is_default": false,
        "label": "Green",
        "sort_order": 0,
        "value_data": {},
        "id": 0
      }
    ],
    "name": "Add-a-$5-Donation1535042499-187"
  },
  "meta": {}
}

Update a Product Variant Option

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/options/{option_id}

Request

Updates a Variant Option.

Read-Only Fields

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.
option_id in path - integer - required
The ID of the Option.

Body

application/json

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

idinteger
The unique numerical ID of the option, increments sequentially.
Example: 55
product_idinteger
The unique numerical ID of the product to which the option belongs.
Example: 4
display_namestring
The name of the option shown on the storefront.
>= 1 characters<= 255 characters
Example: Add-a-$5-Donation1535042499-187
typestring
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
configobject
The values for option config can vary based on the Modifier created.
sort_orderinteger
Order in which the option is displayed on the storefront.
Example: 1
option_valuesarray[object]
image_urlstring
Publicly available image url

example

{
  "id": 55,
  "product_id": 4,
  "display_name": "Add-a-$5-Donation1535042499-187",
  "type": "radio_buttons",
  "config": {
    "default_value": "string",
    "checked_by_default": true,
    "checkbox_label": "string",
    "date_limited": true,
    "date_limit_mode": "range",
    "date_earliest_value": "2018-08-31T00:00:00+00:00",
    "date_latest_value": "2019-01-01T00:00:00+00:00",
    "file_types_mode": "specific",
    "file_types_supported": [
      "images",
      "documents",
      "other"
    ],
    "file_types_other": [
      "pdf",
      "txt"
    ],
    "file_max_size": 5,
    "text_characters_limited": true,
    "text_min_length": 1,
    "text_max_length": 55,
    "text_lines_limited": true,
    "text_max_lines": 4,
    "number_limited": true,
    "number_limit_mode": "lowest",
    "number_lowest_value": 100,
    "number_highest_value": 0,
    "number_integers_only": false,
    "product_list_adjusts_inventory": true,
    "product_list_adjusts_pricing": true,
    "product_list_shipping_calc": "weight"
  },
  "sort_order": 1,
  "option_values": [
    {
      "is_default": false,
      "label": "Green",
      "sort_order": 0,
      "value_data": {},
      "id": 0
    }
  ],
  "image_url": "string"
}

Response

Body

object | application/json

dataobject
metaobject
Response metadata.

example

{
  "data": {
    "id": 220,
    "product_id": 192,
    "name": "Color (Colors only)",
    "display_name": "Color",
    "type": "swatch",
    "sort_order": 0,
    "option_values": [
      {
        "id": 174,
        "label": "Beige",
        "sort_order": 1,
        "value_data": {
          "colors": [
            "#FAFAEB"
          ]
        },
        "is_default": false
      },
      {
        "id": 175,
        "label": "Grey",
        "sort_order": 2,
        "value_data": {
          "colors": [
            "#BDBDBD"
          ]
        },
        "is_default": false
      },
      {
        "id": 176,
        "label": "Black",
        "sort_order": 3,
        "value_data": {
          "colors": [
            "#000000"
          ]
        },
        "is_default": false
      },
      {
        "id": 189,
        "label": "Black-Walnut",
        "sort_order": 4,
        "value_data": {
          "colors": [
            "#e80ee8"
          ]
        },
        "is_default": false
      }
    ],
    "config": {}
  },
  "meta": {}
}

Delete a Product Variant Option

DELETE https://api.bigcommerce.com/stores/{store_hash}/v3/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.
option_id in path - integer - required
The ID of the Option.

example

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/products/[product_id]/options/[option_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Catalog - Product Variant Options

Resources

Webhooks

Additional Catalog endpoints

Get All Product Variant Options

Request

Authentication

Parameters

example

Response

Body

dataarray[object]

metaobject

example

Create a Product Variant Option

Request

Authentication

Parameters

Body

product_idinteger

display_namestring

typestring

configobject

sort_orderinteger

option_valuesarray[object]

image_urlstring

example

Response

Body

dataobject

metaobject

example-1

example-2

Get a Product Variant Option

Request

Authentication

Parameters

example

Response

Body

data

metaobject

example

Update a Product Variant Option

Request

Authentication

Parameters

Body

idinteger

product_idinteger

display_namestring

typestring

configobject

sort_orderinteger

option_valuesarray[object]

image_urlstring

example

Response

Body

dataobject

metaobject

example

Delete a Product Variant Option

Request

Authentication

Parameters

example

Response