Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: BigCommerce Catalog Product Variant Options API
description: "> The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog).\n\nProduct 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.\n\nThe following table illustrates the relationship between Variant Options and Variant Option values using a line of signature sneakers as an example. \n\n| Variant options | Variant option values | No. of variants |\n|:-|:-|-:|\n| size (US Women's) | 6, 6.5, 7, 7.5, 8, 8.5, 9, 9.5, 10, 10.5 | 10 |\n| upper material | canvas, marine plastic, leather | 3 |\n| upper color | brick, azul, gold | 3 |\n| sole color | charcoal, white, azul | 3 |\n| | | **270** |\n\n\nOur Catalog Product Variant Options endpoints let you work with both Variant Options and Variant Option Values. \n\n> To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**.\n\n## Resources\n\n### Webhooks\nLearn more about [Product webhook events](/docs/integrations/webhooks/events#products).\n\n### Additional Catalog endpoints\n* [Brands](/docs/rest-catalog/brands)\n* [Categories](/docs/rest-catalog/categories)\n* [Category Trees](/docs/rest-catalog/category-trees)\n* [Products](/docs/rest-catalog/products)\n* [Product Modifiers](/docs/rest-catalog/product-modifiers)\n* [Product Variants](/docs/rest-catalog/product-variants)"
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: support@bigcommerce.com
version: ''
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
variables:
store_hash:
default: store_hash
description: Permanent ID of the BigCommerce store.
description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Product Variant Options
paths:
/catalog/products/{product_id}/options:
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/ProductIdParam'
get:
tags:
- Product Variant Options
summary: BigCommerce Get All Product Variant Options
description: 'Returns a list of product *Variant Options*. Optional parameters can be passed in. '
operationId: getProductVariantOptions
parameters:
- name: page
in: query
description: Specifies the page number in a limited (paginated) list of products.
schema:
type: integer
- name: limit
in: query
description: Controls the number of items per page in a limited (paginated) list of products.
schema:
type: integer
- name: include_fields
in: query
description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
schema:
type: string
- name: exclude_fields
in: query
description: Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: Option Collection Response
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/productOption_Full'
meta:
$ref: '#/components/schemas/metaCollection_Full'
description: Get all product options
'404':
description: 'The resource was not found.
'
content:
application/json:
schema:
title: Not Found
type: object
properties:
status:
type: integer
description: '404 HTTP status code.
'
title:
type: string
description: The error title describing the particular error.
type:
type: string
instance:
type: string
description: Error payload for the BigCommerce API.
post:
tags:
- Product Variant Options
summary: BigCommerce Create a Product Variant Option
description: '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](/docs/rest-catalog/products#create-a-product) endpoint.'
operationId: createProductVariantOption
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
title: Option Post
description: The model for a POST to create options on a product.
allOf:
- title: Option Base
description: Common Option properties.
properties:
product_id:
type: integer
description: 'The unique numerical ID of the product to which the option belongs.
'
example: 4
x-required:
- post
- put
display_name:
maxLength: 255
minLength: 1
type: string
description: 'The name of the option shown on the storefront.
'
example: Add-a-$5-Donation1535042499-187
x-required:
- post
- put
type:
type: string
description: '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.
'
enum:
- radio_buttons
- rectangles
- dropdown
- product_list
- product_list_with_images
- swatch
x-required:
- post
- put
config:
title: Option Config
type: object
description: The values for option config can vary based on the Modifier created.
properties:
default_value:
type: string
description: '(date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string.
'
checked_by_default:
type: boolean
description: '(checkbox) Flag for setting the checkbox to be checked by default.
'
checkbox_label:
type: string
description: '(checkbox) Label displayed for the checkbox option.
'
date_limited:
type: boolean
description: '(date) Flag to limit the dates allowed to be entered on a date option.
'
date_limit_mode:
type: string
description: '(date) The type of limit that is allowed to be entered on a date option.
'
example: range
enum:
- earliest
- range
- latest
date_earliest_value:
type: string
description: '(date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string.
'
format: date-time
example: '2018-08-31T00:00:00+00:00'
date_latest_value:
type: string
description: '(date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string.
'
format: date-time
example: '2019-01-01T00:00:00+00:00'
file_types_mode:
type: string
description: '(file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types.
'
example: specific
enum:
- specific
- all
file_types_supported:
type: array
description: "(file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values:\n `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`).\n `other` - Allows file types defined in the `file_types_other` array.\n"
example:
- images
- documents
- other
items:
type: string
file_types_other:
type: array
description: '(file) A list of other file types allowed with the file upload option.
'
example:
- pdf
- txt
items:
type: string
file_max_size:
type: integer
description: '(file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server.
'
example: 5
text_characters_limited:
type: boolean
description: '(text, multi_line_text) Flag to validate the length of a text or multi-line text input.
'
text_min_length:
type: integer
description: '(text, multi_line_text) The minimum length allowed for a text or multi-line text option.
'
example: 1
text_max_length:
type: integer
description: '(text, multi_line_text) The maximum length allowed for a text or multi line text option.
'
example: 55
text_lines_limited:
type: boolean
description: '(multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input.
'
example: true
text_max_lines:
type: integer
description: '(multi_line_text) The maximum number of lines allowed on a multi-line text input.
'
example: 4
number_limited:
type: boolean
description: '(numbers_only_text) Flag to limit the value of a number option.
'
example: true
number_limit_mode:
type: string
description: '(numbers_only_text) The type of limit on values entered for a number option.
'
example: lowest
enum:
- lowest
- highest
- range
number_lowest_value:
type: number
description: '(numbers_only_text) The lowest allowed value for a number option if `number_limited` is true.
'
example: 100
number_highest_value:
type: number
description: '(numbers_only_text) The highest allowed value for a number option if `number_limited` is true.
'
number_integers_only:
type: boolean
description: '(numbers_only_text) Flag to limit the input on a number option to whole numbers only.
'
example: false
product_list_adjusts_inventory:
type: boolean
description: '(product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list.
'
product_list_adjusts_pricing:
type: boolean
description: '(product_list, product_list_with_images) Flag to add the optional product''s price to the main product''s price.
'
product_list_shipping_calc:
type: string
description: '(product_list, product_list_with_images) How to factor the optional product''s weight and package dimensions into the shipping quote. Values: `none` - don''t adjust; `weight` - use shipping weight only; `package` - use weight and dimensions.
'
example: weight
enum:
- none
- weight
- package
sort_order:
type: integer
description: 'Order in which the option is displayed on the storefront. '
example: 1
option_values:
minItems: 1
type: array
x-required:
- post
- put
items:
title: Option Value
allOf:
- title: Option Value Base
description: Common Option Value properties.
properties:
is_default:
type: boolean
description: 'The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers.
'
example: false
label:
type: string
description: 'The text display identifying the value on the storefront. Required in a /POST.
'
example: Green
x-required:
- post
sort_order:
maximum: 2147483647
minimum: -2147483648
type: integer
description: 'The order in which the value will be displayed on the product page. Required in a /POST.
'
example: 0
x-required:
- post
value_data:
type: object
properties: {}
description: 'Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state.
'
required:
- label
- sort_order
- properties:
id:
type: integer
description: 'The unique numeric ID of the value; increments sequentially.
'
type: object
image_url:
type: string
description: Publicly available image url
type: object
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
title: Option Response
type: object
properties:
data:
title: Option
type: object
allOf:
- title: Option Base
description: Common Option properties.
type: object
properties:
id:
type: integer
description: 'The unique numerical ID of the option, increments sequentially.
'
example: 55
x-nullable: true
product_id:
type: integer
description: 'The unique numerical ID of the product to which the option belongs.
'
example: 4
x-required:
- post
- put
display_name:
maxLength: 255
minLength: 1
type: string
description: 'The name of the option shown on the storefront.
'
example: Add-a-$5-Donation1535042499-187
x-required:
- post
- put
type:
type: string
description: '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.
'
enum:
- radio_buttons
- rectangles
- dropdown
- product_list
- product_list_with_images
- swatch
x-required:
- post
- put
config:
title: Option Config
type: object
description: The values for option config can vary based on the Modifier created.
properties:
default_value:
type: string
description: '(date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string.
'
checked_by_default:
type: boolean
description: '(checkbox) Flag for setting the checkbox to be checked by default.
'
checkbox_label:
type: string
description: '(checkbox) Label displayed for the checkbox option.
'
date_limited:
type: boolean
description: '(date) Flag to limit the dates allowed to be entered on a date option.
'
date_limit_mode:
type: string
description: '(date) The type of limit that is allowed to be entered on a date option.
'
example: range
enum:
- earliest
- range
- latest
date_earliest_value:
type: string
description: '(date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string.
'
format: date-time
date_latest_value:
type: string
description: '(date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string.
'
format: date-time
file_types_mode:
type: string
description: '(file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types.
'
example: specific
enum:
- specific
- all
file_types_supported:
type: array
description: "(file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values:\n `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`).\n `other` - Allows file types defined in the `file_types_other` array.\n"
items:
type: string
example: images, documents, other
file_types_other:
type: array
description: '(file) A list of other file types allowed with the file upload option.
'
items:
type: string
example: pdf
file_max_size:
type: integer
description: '(file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server.
'
example: 5
text_characters_limited:
type: boolean
description: '(text, multi_line_text) Flag to validate the length of a text or multi-line text input.
'
text_min_length:
type: integer
description: '(text, multi_line_text) The minimum length allowed for a text or multi-line text option.
'
example: 1
text_max_length:
type: integer
description: '(text, multi_line_text) The maximum length allowed for a text or multi line text option.
'
example: 55
text_lines_limited:
type: boolean
description: '(multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input.
'
example: true
text_max_lines:
type: integer
description: '(multi_line_text) The maximum number of lines allowed on a multi-line text input.
'
example: 4
number_limited:
type: boolean
description: '(numbers_only_text) Flag to limit the value of a number option.
'
example: true
number_limit_mode:
type: string
description: '(numbers_only_text) The type of limit on values entered for a number option.
'
example: lowest
enum:
- lowest
- highest
- range
number_lowest_value:
type: number
description: '(numbers_only_text) The lowest allowed value for a number option if `number_limited` is true.
'
example: 100
number_highest_value:
type: number
description: '(numbers_only_text) The highest allowed value for a number option if `number_limited` is true.
'
number_integers_only:
type: boolean
description: '(numbers_only_text) Flag to limit the input on a number option to whole numbers only.
'
example: false
product_list_adjusts_inventory:
type: boolean
description: '(product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list.
'
product_list_adjusts_pricing:
type: boolean
description: '(product_list, product_list_with_images) Flag to add the optional product''s price to the main product''s price.
'
product_list_shipping_calc:
type: string
description: '(product_list, product_list_with_images) How to factor the optional product''s weight and package dimensions into the shipping quote. Values: `none` - don''t adjust; `weight` - use shipping weight only; `package` - use weight and dimensions.
'
example: weight
enum:
- none
- weight
- package
sort_order:
type: integer
description: 'Order in which the option is displayed on the storefront. '
example: 1
option_values:
minItems: 1
type: array
x-required:
- post
- put
items:
title: Option Value
allOf:
- title: Option Value Base
description: Common Option Value properties.
properties:
is_default:
type: boolean
description: 'The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers.
'
example: false
label:
type: string
description: 'The text display identifying the value on the storefront. Required in a /POST.
'
example: Green
x-required:
- post
sort_order:
maximum: 2147483647
minimum: -2147483648
type: integer
description: 'The order in which the value will be displayed on the product page. Required in a /POST.
'
example: 0
x-required:
- post
value_data:
type: object
properties: {}
description: 'Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state.
'
required:
- label
- sort_order
- properties:
id:
type: integer
# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-product-variant-options-api-openapi.yml