openapi: 3.0.0
info:
title: BigCommerce Abandoned Cart Emails Product Modifiers API
version: 3.0.0
termsOfService: https://www.bigcommerce.com/terms
description: Abandoned Cart Emails V3 API managing Handlebars-based emails.
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: support@bigcommerce.com
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 Modifiers
paths:
/catalog/products/{product_id}/modifiers:
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/ProductIdParam'
get:
tags:
- Product Modifiers
summary: BigCommerce Get All Product Modifiers
description: Returns a list of all *Product Modifiers*. Optional parameters can be passed in.
operationId: getProductModifiers
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: Modifier Collection Response
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/productModifier_Full'
meta:
$ref: '#/components/schemas/metaCollection_Full'
description: Modifier Collection Response return for /GET All Modifiers.
example:
data:
- id: 206
product_id: 158
name: Insurance
display_name: Insurace
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: ''
purchasing_disabled:
status: false
message: ''
- id: 184
option_id: 206
label: 'No'
sort_order: 1
value_data:
checked_value: false
is_default: true
adjusters:
price: {}
weight: {}
image_url: ''
purchasing_disabled:
status: false
message: ''
meta:
pagination:
total: 1
count: 1
per_page: 50
current_page: 1
total_pages: 1
links:
current: ?page=1&limit=50
post:
tags:
- Product Modifiers
summary: BigCommerce Create a Product Modifier
description: '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.'
operationId: createProductModifier
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
title: Modifier Post
description: The model for a POST to create a modifier on a product.
allOf:
- title: Modifier Base
required:
- required
- type
type: object
properties:
type:
type: string
description: '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.
'
enum:
- date
- checkbox
- file
- text
- multi_line_text
- numbers_only_text
- radio_buttons
- rectangles
- dropdown
- product_list
- product_list_with_images
- swatch
x-required:
- post
required:
type: boolean
description: 'Whether or not this modifer is required or not at checkout. Required in a /POST.
'
x-required:
- post
sort_order:
type: integer
description: The order the modifiers display on the product detail page.
config:
title: Option Config
type: object
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
description: The values for option config can vary based on the Modifier created.
option_values:
type: array
items:
title: Modifier Value
type: object
description: 'Part of Modifier Value Response '
allOf:
- title: Modifier Value Base
type: object
allOf:
- title: Option Value Base
required:
- label
- sort_order
type: object
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.
'
description: Common Option Value properties.
- type: object
properties:
adjusters:
type: object
properties:
price:
title: Adjuster
type: object
properties:
adjuster:
type: string
description: 'The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront.
'
enum:
- relative
- percentage
x-nullable: true
adjuster_value:
type: number
description: 'The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront.
'
example: 5
description: Adjuster for Complex Rules.
weight:
title: Adjuster
type: object
properties:
adjuster:
type: string
description: 'The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront.
'
enum:
- relative
- percentage
x-nullable: true
adjuster_value:
type: number
description: 'The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront.
'
example: 5
description: Adjuster for Complex Rules.
image_url:
type: string
description: 'The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file.
'
example: https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2
purchasing_disabled:
type: object
properties:
status:
type: boolean
description: 'Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value.
'
message:
type: string
description: 'The message displayed on the storefront when the purchasing disabled status is `true`.
'
- type: object
properties:
id:
type: integer
description: 'The unique numeric ID of the value; increments sequentially.
'
description: Common Modifier properties.
- required:
- display_name
type: object
properties:
display_name:
type: string
description: 'The name of the option shown on the storefront.
'
example: Donation
x-required:
- post
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
title: Modifier Response
type: object
properties:
data:
title: Modifer
type: object
description: Product Modifier
allOf:
- title: Modifier Base
required:
- required
- type
type: object
properties:
type:
type: string
description: '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.
'
enum:
- date
- checkbox
- file
- text
- multi_line_text
- numbers_only_text
- radio_buttons
- rectangles
- dropdown
- product_list
- product_list_with_images
- swatch
x-required:
- post
required:
type: boolean
description: 'Whether or not this modifer is required or not at checkout. Required in a /POST.
'
x-required:
- post
sort_order:
type: integer
description: The order the modifiers display on the product detail page.
config:
title: Option Config
type: object
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
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
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
description: The values for option config can vary based on the Modifier created.
option_values:
type: array
items:
title: Modifier Value
type: object
description: 'Part of Modifier Value Response '
allOf:
- title: Modifier Value Base
type: object
allOf:
- title: O
# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-product-modifiers-api-openapi.yml