Docs
Catalog API
Product modifiers

Catalog - Product modifiers

The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the Catalog Overview.

Product modifiers represent choices that the shopper can make to change how the merchant customizes or adds on to the product. Examples include shipping insurance, monograms, custom inseam length, and color selections for unfinished products.

Modifier values do not change which item is picked in a warehouse, but they change what happens to that item between the warehouse shelf and the shopper taking possession of their order.

Critically, modifier values do not change which product variant is fulfilled. You cannot track inventory for combinations of modifier values.

You can add an adjuster to a modifier value to override the underlying product variant's properties, such as price, weight, and shipping rules. Not all modifier types are compatible with adjusters.

To learn more about authenticating Catalog endpoints, locate the Authentication section at the top of each endpoint, then click Show Details.

Option Values and Configs

Modifiers endpoints include many fields with data that are specific to one or more type values, as different modifier option types have different functionality. This information is contained in the option_values array and the config object. See the tables below for details on the fields available for each modifier type.

Option Values

Modifier types that present choices to the shopper use an option_values array. Each entry defines a possible value for that modifier, along with display text, ordering, and adjusters for price, weight, and more. This is not used for modifier types that do not present choices, including text, multi_line_text, numbers_only_text, date, and file.

FieldDescriptionApplies to Types
is_defaultWhether this value is selected by default; not supported by the swatch typeAll with options (except swatch)
labelStorefront display text for the option valueAll with options
sort_orderDisplay order of the value on product pagesAll with options
value_data
  • swatch — can include a colors array with up to three hexidecimal color keys or an image_url field with a full image URL path including procotol for a custom pattern
  • product list/product list with images — uses the product_id field to identify the product in the list
  • checkbox — uses the boolean checked_value field to indicate whether the option value is the "checked" state.
swatch, product list, product list with images, checkbox
adjusters.pricePrice adjustment for complex rules. Defines whether the price adjustment is relative (fixed) or percentage, and sets the amount to adjust the price.All with options
adjusters.weightWeight adjustment for complex rules on physical products. Defines whether the weight adjustment is relative (fixed) or percentage, and sets the amount to adjust the weight.All with options
adjusters.image_urlThe full URL path for the image displayed when the value is selected on the storefront product page. The image file can have a maximum size of 8 MB.All with options
adjusters.purchasing_disabledDefines whether or not the option value is purchasable. If purchasing is disabled, you can specify a message to appear when the value is selected on the storefront.All with options
idUnique numeric ID for the option value; not used in /POST requestsAll with options
option_idModifier ID this value belongs toAll with options

Configs

The config object customizes the behavior and validation of a modifier. Available fields depend on the type of modifier, such as text, date, file, or product list. Note that the multiple choice option types (radio_buttons, rectangles, dropdown, swatch) do not have option configs, as they only use fields in the option_values array.

Modifier Type(s)Config FieldDescription or Values
datedefault_valueDefault ISO date string
date_limitedBoolean: Indicates whether the allowed date options are limited
date_limit_modeDefines the type of limit on the date option. Accepts earliest, range, and latest.
date_earliest_valueISO date: the earliest date allowed to be entered on the date option
date_latest_valueISO date: the latest date allowed to be entered on the date option
checkboxchecked_by_defaultBoolean: Indicates whether the option is checked by default
checkbox_labelThe label that appears next to the checkbox on the storefront
filefile_types_modeSpecifies whether you want to allow shoppers to upload any file type or if you only want to accept particular types defined in the file_types_supported array.
file_types_supportedSpecifies groups of file types to accept for upload. See Supported File Types to learn more.
file_types_otherList specific file types to accept for upload
file_max_sizeInteger: the max file size in KB to accept for upload. This cannot exceed 524,288 KB.
text, multi_line_textdefault_valueString: the default value that appears in the text box
text_characters_limitedBoolean: Indicates whether the field validates the character count with a minimum and maximum value
text_min_lengthInteger: Specifies the minimum allowed characters
text_max_lengthInteger: Specifies the maximum allowed characters
multi_line_texttext_lines_limitedBoolean: Indicates whether the field limits the number of text lines
text_max_linesInteger: Specifies the maximum allowed lines
numbers_only_textdefault_valueString/number: the default value that appears in the number box
number_limitedBoolean: Indicates whether the field validates the entered number with a minimum and maximum value
number_limit_modeDefines the type of limit on the number option. Accepts lowest, range, and highest.
number_lowest_valueNumber: Specifies the minimum value
number_highest_valueNumber: Specifies the maximum value
number_integers_onlyBoolean: Indicates whether the field accepts decimals or whole numbers only
product_list, product_list_with_imagesproduct_list_adjusts_inventoryIndicates whether selecting and purchasing a product in the list adjusts that product's inventory
product_list_adjusts_pricingIndicates whether selecting a product in the list adds its price to the main product's price
product_list_shipping_calcSpecifies how to factor weight and package dimensions when selecting a product in the list. Use weight to add the list product's weight to the main product, package to add the list product's weight and dimensions, or none to not adjust the main product's weight and dimensions.

Supported File Types

The file modifier type allows you to restrict the file types that can be uploaded by a shopper by setting the file_types_mode to specific. You can then use the file_types_supported and file_types_other arrays to specify the allowed file types. The following file types are supported:

File Type CategoryIncluded File Types
imagesbmp, gif, jpg, jpeg, jpe, jif, jfif, jfi, png, wbmp, xbm, tiff
documentstxt, pdf, rtf, doc, docx, xls, xlsx, accdb, mdb, one, pps, ppsx, ppt, pptx, pub, odt, ods, odp, odg, odf
otherCustom file types defined in the file_types_other array

Resources

Webhooks

Learn more about Product webhook events.

Additional Catalog endpoints

Get all product modifiers

GET /catalog/products/{product_id}/modifiers

Request

Returns a list of all product modifiers. Optional parameters can be passed in.

Authentication

  • X-Auth-Token in header

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.

  • include_fields in query - array
    Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
    Type: array[string]
  • exclude_fields in query - array
    Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
    Type: array[string]
  • page in query - integer

    Specifies the page number in a limited (paginated) list of products.

  • limit in query with default of 50 - integer

    Controls the number of items per page in a limited (paginated) list of products.

example

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

Response

Body

object | application/json
Modifier Collection Response return for /GET All Modifiers.

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals.

example

{
"data": [
{
"id": 206,
"product_id": 158,
"name": "Insurance",
"display_name": "Insurance",
"type": "checkbox",
"required": true,
"config": {
"checkbox_label": "$5 for insurance",
"checked_by_default": false
},
"option_values": [
{
"id": 183,
"option_id": 206,
"label": "Yes",
"sort_order": 0,
"value_data": {
"checked_value": true
},
"is_default": false,
"adjusters": {
"price": {},
"weight": {},
"image_url": "",

Create a product modifier

POST /catalog/products/{product_id}/modifiers

Request

Creates a product modifier.

Required Fields

  • required
  • display_name
  • type

Read-Only Fields

  • id

Notes It takes two separate requests to create a new checkbox modifier with option values. Perform a request to create a modifier, then perform a second request to update option values.

Authentication

  • X-Auth-Token in header

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.

  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json
Common Modifier properties.

  • type    string
    required

    BigCommerce API, which determines how it will display on the storefront. Acceptable values: date, checkbox, file, text, multi_line_text, numbers_only_text, radio_buttons, rectangles, dropdown, product_list, product_list_with_images, swatch. Required in a /POST.

    Allowed: date | checkbox | file | text | multi_line_text | numbers_only_text | radio_buttons | rectangles | dropdown | product_list | product_list_with_images | swatch

  • required    boolean
    required

    Whether or not this modifier is required at checkout. Required in a /POST.

  • sort_order    integer

    The order the modifiers display on the product detail page.

  • config    object

    The values for option config can vary based on the Modifier created. See Configs to learn more about the type-specific config fields.

  • option_values    array[object]

    Contains information about the values for modifier types with options. Certain fields are not used for specific modifier types. See Option Values for more details.

  • display_name    string
    required

    The name of the option shown on the storefront.

example

{
"type": "radio_buttons",
"required": true,
"sort_order": 0,
"option_values": [
{
"is_default": false,
"label": "+5",
"sort_order": 0,
"value_data": {},
"adjusters": {
"price": {
"adjuster": "relative",
"adjuster_value": 5
},
"weight": {
"adjuster": "relative",
"adjuster_value": 5
},
"purchasing_disabled": {
"status": true,
"message": "string"
}
}
},
{
"is_default": false,
"label": "+10",
"sort_order": 0,
"value_data": {},

Response

Body

object | application/json

  • data    object

  • meta    object

    Response metadata.

example

{
"data": {
"id": 164,
"product_id": 161,
"name": "Test-name1716906851-161",
"display_name": "Test name",
"type": "radio_buttons",
"required": true,
"sort_order": 0,
"config": [],
"option_values": [
{
"id": 199,
"option_id": 164,
"label": "+5",
"sort_order": 0,
"value_data": null,
"is_default": false,
"adjusters": {
"price": {
"adjuster": "relative",
"adjuster_value": 5
},
"weight": {
"adjuster": "relative",
"adjuster_value": 5
},
"image_url": "",

Get a product modifier

GET /catalog/products/{product_id}/modifiers/{modifier_id}

Request

Returns a single product modifier. Optional parameters can be passed in.

Authentication

  • X-Auth-Token in header

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.

  • modifier_id in path - integer
    required

    The ID of the product modifier.

  • include_fields in query - array
    Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
    Type: array[string]
  • exclude_fields in query - array
    Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
    Type: array[string]

example

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

Response

Body

object | application/json

  • data    object

    Product modifier

  • meta    object

    Response metadata.

example

{
"data": {
"type": "date",
"required": true,
"sort_order": 0,
"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,

Update a product modifier

PUT /catalog/products/{product_id}/modifiers/{modifier_id}

Request

Updates a product modifier.

Authentication

  • X-Auth-Token in header

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.

  • modifier_id in path - integer
    required

    The ID of the product modifier.

  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.
Common Modifier properties.

Body

object | application/json
The model for a PUT to update a modifier on a product.

  • type    string
    required

    BigCommerce API, which determines how it will display on the storefront. Acceptable values: date, checkbox, file, text, multi_line_text, numbers_only_text, radio_buttons, rectangles, dropdown, product_list, product_list_with_images, swatch. Required in a /POST.

    Allowed: date | checkbox | file | text | multi_line_text | numbers_only_text | radio_buttons | rectangles | dropdown | product_list | product_list_with_images | swatch

  • required    boolean
    required

    Whether or not this modifier is required at checkout. Required in a /POST.

  • sort_order    integer

    The order the modifiers display on the product detail page.

  • config    object

    The values for option config can vary based on the Modifier created. See Configs to learn more about the type-specific config fields.

  • option_values    array[object]

    Contains information about the values for modifier types with options. Certain fields are not used for specific modifier types. See Option Values for more details.

  • display_name    string

    The name of the option shown on the storefront.

    Example: Donation

example

{
"type": "date",
"required": true,
"sort_order": 0,
"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,

Response

Body

object | application/json

  • data    object

    Product modifier

  • meta    object

    Response metadata.

example

{
"data": {
"type": "date",
"required": true,
"sort_order": 0,
"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,

Delete a product modifier

DELETE /catalog/products/{product_id}/modifiers/{modifier_id}

Request

Deletes a product modifier.

Authentication

  • X-Auth-Token in header

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.

  • modifier_id in path - integer
    required

    The ID of the product modifier.

example

curl --request DELETE \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/catalog/products/[product_id]/modifiers/[modifier_id]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?
Delete a Product VideoGet all product modifiers