BigCommerce Catalog - Product Variant Options is a feature that allows online retailers to easily set up and manage different options for their products, such as color, size, and style variations. This helps customers to easily select the specific product they want to purchase, as well as simplifying inventory management and order processing for the retailer.
openapi: 3.0.3
info:
title: BigCommerce Catalog - Product Variant Options
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).
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](/docs/integrations/webhooks/events#products).
### Additional Catalog endpoints
* [Brands](/docs/rest-catalog/brands)
* [Categories](/docs/rest-catalog/categories)
* [Category Trees](/docs/rest-catalog/category-trees)
* [Products](/docs/rest-catalog/products)
* [Product Modifiers](/docs/rest-catalog/product-modifiers)
* [Product Variants](/docs/rest-catalog/product-variants)
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: [email protected]
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
- name: Values
paths:
/catalog/products/{product_id}/options:
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:
`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`).
`other` - Allows file types defined in the `file_types_other` array.
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:
`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`).
`other` - Allows file types defined in the `file_types_other` array.
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:
# --- truncated at 32 KB (125 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/catalog-product-variant-options-openapi-original.yml