POST /catalog/products/{product_id}/options

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.

Servers

https://api.bigcommerce.com/stores/{store_hash}/v3

Path parameters

Name	Type	Required	Description
`product_id`	Integer	Yes	The ID of the `Product` to which the resource belongs.

Request headers

Name Type Required Description

Name	Type	Required	Description
`Accept`	String	Yes	The MIME type of the response body. Default value: "application/json"
`Content-Type`	String	Yes	The MIME type of the request body. Default value: "application/json"

Accept

String

Yes

The MIME type of the response body.

Default value: "application/json"

Content-Type

String

Yes

The MIME type of the request body.

Default value: "application/json"

Request body fields

Name	Type	Required	Description
`sort_order`	Integer	No	Order in which the option is displayed on the storefront.
`config`	Object	No	The values for option config can vary based on the Modifier created.
`config.product_list_shipping_calc`	String	No	(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. Valid values: `"package"` `"weight"` `"none"`
`config.file_types_mode`	String	No	(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. Valid values: `"specific"` `"all"`
`config.date_limit_mode`	String	No	(date) The type of limit that is allowed to be entered on a date option. Valid values: `"range"` `"earliest"` `"latest"`
`config.number_highest_value`	Number	No	(numbers_only_text) The highest allowed value for a number option if `number_limited` is true.
`config.file_max_size`	Integer	No	(file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server.
`config.number_lowest_value`	Number	No	(numbers_only_text) The lowest allowed value for a number option if `number_limited` is true.
`config.date_earliest_value`	String	No	(date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string.
`config.number_integers_only`	Boolean	No	(numbers_only_text) Flag to limit the input on a number option to whole numbers only.
`config.date_latest_value`	String	No	(date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string.
`config.number_limit_mode`	String	No	(numbers_only_text) The type of limit on values entered for a number option. Valid values: `"lowest"` `"range"` `"highest"`
`config.default_value`	String	No	(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.
`config.text_min_length`	Integer	No	(text, multi_line_text) The minimum length allowed for a text or multi-line text option.
`config.checked_by_default`	Boolean	No	(checkbox) Flag for setting the checkbox to be checked by default.
`config.product_list_adjusts_inventory`	Boolean	No	(product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list.
`config.checkbox_label`	String	No	(checkbox) Label displayed for the checkbox option.
`config.text_characters_limited`	Boolean	No	(text, multi_line_text) Flag to validate the length of a text or multi-line text input.
`config.number_limited`	Boolean	No	(numbers_only_text) Flag to limit the value of a number option.
`config.file_types_other[]`	Array	No	(file) A list of other file types allowed with the file upload option.
`config.text_lines_limited`	Boolean	No	(multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input.
`config.text_max_length`	Integer	No	(text, multi_line_text) The maximum length allowed for a text or multi line text option.
`config.date_limited`	Boolean	No	(date) Flag to limit the dates allowed to be entered on a date option.
`config.file_types_supported[]`	Array	No	(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.
`config.product_list_adjusts_pricing`	Boolean	No	(product_list, product_list_with_images) Flag to add the optional product's price to the main product's price.
`config.text_max_lines`	Integer	No	(multi_line_text) The maximum number of lines allowed on a multi-line text input.
`display_name`	String	No	The name of the option shown on the storefront.
`type`	String	No	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. Valid values: `"rectangles"` `"dropdown"` `"radio_buttons"` `"swatch"` `"product_list"` `"product_list_with_images"`
`option_values[]`	Array	No
`option_values[].id`	Integer	No	The unique numeric ID of the value; increments sequentially.
`option_values[].is_default`	Boolean	No	The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers.
`option_values[].sort_order`	Integer	Yes	The order in which the value will be displayed on the product page. Required in a /POST.
`option_values[].label`	String	Yes	The text display identifying the value on the storefront. Required in a /POST.
`option_values[].value_data`	Object	No	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.
`product_id`	Integer	No	The unique numerical ID of the product to which the option belongs.
`image_url`	String	No	Publicly available image url

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.