> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # Create Product Modifier POST https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/modifiers Content-Type: application/json Creates a product modifier. **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. Date modifiers are required to be provided in [ISO-8601 ATOM](https://www.php.net/manual/en/class.datetimeinterface.php#datetimeinterface.constants.atom) format. Excluding them in a request will throw a server error. **Setting an option value image** `adjusters.image_url` is read-only on this endpoint. To attach or replace the image shown on the storefront for an option value, upload it via [Create Product Modifier Image](/developer/api-reference/rest/admin/catalog/product-modifiers/images/create-product-modifier-image). The upload binds the image to the value automatically; no follow-up call is needed. Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-modifiers/create-product-modifier ## Authentication - `X-Auth-Token` header (required) — ### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Products | modify | `store_v2_products` | | Products | read-only | `store_v2_products_read_only` | ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes). ## Request ### Path parameters - `product_id` (integer, required) — The ID of the product to which the resource belongs. - `store_hash` (string, required) — Permanent ID of the BigCommerce store. ### Headers - `Accept` (string, required, default: application/json) — The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body. ### Body (application/json) This endpoint expects a productModifier_Post. - `type` (enum, 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 values: `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. - `display_name` (string, required) — The name of the option shown on the storefront. - `sort_order` (integer, optional) — The order the modifiers display on the product detail page. - `config` (config_Full, optional) — The values for option config can vary based on the Modifier created. See [Configs](#configs) to learn more about the type-specific `config` fields. - `option_values` (list of productModifierOptionValue_Post, optional) — Contains information about the values for modifier types with options. Certain fields are not used for specific modifier types. See [Option Values](#option-values) for more details. ## Response ### 200 OK - `data` (productModifier_Full, optional) — Product modifier - `meta` (metaEmpty_Full, optional) — Response metadata. ## Errors ### 409 Conflict Error The `Modifier` was in conflict with another option. This is the result of duplicate unique fields, such as `name`. - `errors` (CatalogProductsProductIdModifiersPostResponsesContentApplicationJsonSchemaErrors, optional) - `instance` (string, optional) - `status` (integer, optional) — The HTTP status code. - `title` (string, optional) — The error title describing the particular error. - `type` (string, optional) ### 422 Unprocessable Entity Error The `Modifier` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - `errors` (CatalogProductsProductIdModifiersPostResponsesContentApplicationJsonSchemaErrors, optional) - `instance` (string, optional) - `status` (integer, optional) — The HTTP status code. - `title` (string, optional) — The error title describing the particular error. - `type` (string, optional) ## Types ### config_Full The values for option config can vary based on the Modifier created. See [Configs](#configs) to learn more about the type-specific `config` fields. - `default_value` (string, optional) — (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601 ATOM formatted string, or on a text option as a string. See [Configs](#configs) for more details. - `checked_by_default` (boolean, optional) — (checkbox) Flag for setting the checkbox to be checked by default. - `checkbox_label` (string, optional) — (checkbox) Label displayed for the checkbox option. - `date_limited` (boolean, optional) — (date) Flag to limit the dates allowed to be entered on a date option. - `date_limit_mode` (enum, optional) — (date) The type of limit that is allowed to be entered on a date option. - Allowed values: `earliest`, `range`, `latest` - `date_earliest_value` (string, optional) — (date) The earliest date allowed to be entered on the date option, as an ISO-8601 ATOM formatted string. - `date_latest_value` (string, optional) — (date) The latest date allowed to be entered on the date option, as an ISO-8601 ATOM formatted string. - `file_types_mode` (enum, optional) — (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. - Allowed values: `specific`, `all` - `file_types_supported` (list of string, optional) — (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. See [Supported File Types](#supported-file-types) for more details. - `file_types_other` (list of string, optional) — (file) A list of other file types allowed with the file upload option. See [Supported File Types](#supported-file-types) for more details. - `file_max_size` (integer, optional) — (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. See [Configs](#configs) for more details. - `text_characters_limited` (boolean, optional) — (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - `text_min_length` (integer, optional) — (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - `text_max_length` (integer, optional) — (text, multi_line_text) The maximum length allowed for a text or multi line text option. - `text_lines_limited` (boolean, optional) — (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - `text_max_lines` (integer, optional) — (multi_line_text) The maximum number of lines allowed on a multi-line text input. - `number_limited` (boolean, optional) — (numbers_only_text) Flag to limit the value of a number option. - `number_limit_mode` (enum, optional) — (numbers_only_text) The type of limit on values entered for a number option. - Allowed values: `lowest`, `highest`, `range` - `number_lowest_value` (double, optional) — (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - `number_highest_value` (double, optional) — (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - `number_integers_only` (boolean, optional) — (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - `product_list_adjusts_inventory` (boolean, optional) — (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - `product_list_adjusts_pricing` (boolean, optional) — (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - `product_list_shipping_calc` (enum, optional) — (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. See [Configs](#configs) for more details. - Allowed values: `none`, `weight`, `package` ### productModifierOptionValue_Post Product modifier `option_value` for POST requests. Adds POST-only required fields on top of the shared base. - `adjusters` (adjusters_Full, optional) - `is_default` (boolean, optional) — The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - `label` (string, optional) — The text display identifying the value on the storefront. Required in a /POST. - `sort_order` (integer, optional) — The order in which the value will be displayed on the product page. Required in a /POST. - `value_data` (ProductModifierOptionValueBaseValueData, optional, nullable) — Extra data describing the value, based on the type of option or modifier with which the value is associated. See [Option Values](#option-values) for more details. ### productModifier_Full Product modifier - `required` (boolean, required) — Whether or not this modifier is required at checkout. Required in a /POST. - `type` (enum, 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 values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch` - `config` (config_Full, optional) — The values for option config can vary based on the Modifier created. See [Configs](#configs) to learn more about the type-specific `config` fields. - `display_name` (string, optional) — The name of the option shown on the storefront. - `id` (integer, optional) — The unique numeric ID of the modifier; increments sequentially. - `name` (string, optional) — The unique option name. Auto-generated from the display name, a timestamp, and the product ID. - `option_values` (list of productModifierOptionValue_Full, optional) — Contains information about the values for modifier types with options. Certain fields are not used for specific modifier types. See [Option Values](#option-values) for more details. - `product_id` (integer, optional) — The unique numeric ID of the product to which the option belongs. - `sort_order` (integer, optional) — The order the modifiers display on the product detail page. ### metaEmpty_Full Response metadata. ### CatalogProductsProductIdModifiersPostResponsesContentApplicationJsonSchemaErrors ### adjusters_Full - `price` (adjuster_Full, optional) — Adjuster for Complex Rules. - `weight` (adjuster_Full, optional) — Adjuster for Complex Rules. - `image_url` (string, optional) — The URL for an image displayed on the storefront when the modifier value is selected. Read-only on modifier and option-value endpoints. To set or replace the image, use the [Create Product Modifier Image](/developer/api-reference/rest/admin/catalog/product-modifiers/images/create-product-modifier-image) endpoint. Limit of 8MB per file. - `purchasing_disabled` (AdjustersFullPurchasingDisabled, optional) ### ProductModifierOptionValueBaseValueData Extra data describing the value, based on the type of option or modifier with which the value is associated. See [Option Values](#option-values) for more details. ### productModifierOptionValue_Full Product modifier `option_value`. - `adjusters` (adjusters_Full, optional) - `id` (integer, optional) — The unique numeric ID of the value; increments sequentially. - `is_default` (boolean, optional) — The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - `label` (string, optional) — The text display identifying the value on the storefront. Required in a /POST. - `option_id` (integer, optional) - `sort_order` (integer, optional) — The order in which the value will be displayed on the product page. Required in a /POST. - `value_data` (ProductModifierOptionValueBaseValueData, optional, nullable) — Extra data describing the value, based on the type of option or modifier with which the value is associated. See [Option Values](#option-values) for more details. ### adjuster_Full Adjuster for Complex Rules. - `adjuster` (enum, optional, nullable) — The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - Allowed values: `relative`, `percentage` - `adjuster_value` (double, optional) — 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. ### AdjustersFullPurchasingDisabled - `status` (boolean, optional) — 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` (string, optional) — The message displayed on the storefront when the purchasing disabled status is `true`. ## Examples **Request** ```json { "type": "radio_buttons", "required": true, "display_name": "Donation", "sort_order": 0, "option_values": [ { "adjusters": { "price": { "adjuster": "relative", "adjuster_value": 5 }, "weight": { "adjuster": "relative", "adjuster_value": 5 }, "purchasing_disabled": { "status": true, "message": "string" } }, "is_default": false, "label": "+5", "sort_order": 0, "value_data": {} }, { "adjusters": { "price": { "adjuster": "relative", "adjuster_value": 10 }, "weight": { "adjuster": "relative", "adjuster_value": 10 }, "purchasing_disabled": { "status": true, "message": "string" } }, "is_default": false, "label": "+10", "sort_order": 0, "value_data": {} } ] } ``` **Response** ```json { "data": { "required": true, "type": "radio_buttons", "config": {}, "display_name": "Test name", "id": 164, "name": "Test-name1716906851-161", "option_values": [ { "adjusters": { "price": { "adjuster": "relative", "adjuster_value": 5 }, "weight": { "adjuster": "relative", "adjuster_value": 5 }, "image_url": "", "purchasing_disabled": { "status": true, "message": "string" } }, "id": 199, "is_default": false, "label": "+5", "option_id": 164, "sort_order": 0, "value_data": null }, { "adjusters": { "price": { "adjuster": "relative", "adjuster_value": 10 }, "weight": { "adjuster": "relative", "adjuster_value": 10 }, "image_url": "", "purchasing_disabled": { "status": true, "message": "string" } }, "id": 200, "is_default": false, "label": "+10", "option_id": 164, "sort_order": 0, "value_data": null } ], "product_id": 161, "sort_order": 0 }, "meta": {} } ``` **SDK Code** ```python Create a product modifier import requests url = "https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/1/modifiers" payload = { "type": "radio_buttons", "required": True, "display_name": "Donation", "sort_order": 0, "option_values": [ { "adjusters": { "price": { "adjuster": "relative", "adjuster_value": 5 }, "weight": { "adjuster": "relative", "adjuster_value": 5 }, "purchasing_disabled": { "status": True, "message": "string" } }, "is_default": False, "label": "+5", "sort_order": 0, "value_data": {} }, { "adjusters": { "price": { "adjuster": "relative", "adjuster_value": 10 }, "weight": { "adjuster": "relative", "adjuster_value": 10 }, "purchasing_disabled": { "status": True, "message": "string" } }, "is_default": False, "label": "+10", "sort_order": 0, "value_data": {} } ] } headers = { "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Create a product modifier const url = 'https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/1/modifiers'; const options = { method: 'POST', headers: { Accept: 'application/json', 'X-Auth-Token': '', 'Content-Type': 'application/json' }, body: '{"type":"radio_buttons","required":true,"display_name":"Donation","sort_order":0,"option_values":[{"adjusters":{"price":{"adjuster":"relative","adjuster_value":5},"weight":{"adjuster":"relative","adjuster_value":5},"purchasing_disabled":{"status":true,"message":"string"}},"is_default":false,"label":"+5","sort_order":0,"value_data":{}},{"adjusters":{"price":{"adjuster":"relative","adjuster_value":10},"weight":{"adjuster":"relative","adjuster_value":10},"purchasing_disabled":{"status":true,"message":"string"}},"is_default":false,"label":"+10","sort_order":0,"value_data":{}}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Create a product modifier package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/1/modifiers" payload := strings.NewReader("{\n \"type\": \"radio_buttons\",\n \"required\": true,\n \"display_name\": \"Donation\",\n \"sort_order\": 0,\n \"option_values\": [\n {\n \"adjusters\": {\n \"price\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 5\n },\n \"weight\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 5\n },\n \"purchasing_disabled\": {\n \"status\": true,\n \"message\": \"string\"\n }\n },\n \"is_default\": false,\n \"label\": \"+5\",\n \"sort_order\": 0,\n \"value_data\": {}\n },\n {\n \"adjusters\": {\n \"price\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 10\n },\n \"weight\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 10\n },\n \"purchasing_disabled\": {\n \"status\": true,\n \"message\": \"string\"\n }\n },\n \"is_default\": false,\n \"label\": \"+10\",\n \"sort_order\": 0,\n \"value_data\": {}\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Accept", "application/json") req.Header.Add("X-Auth-Token", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Create a product modifier require 'uri' require 'net/http' url = URI("https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/1/modifiers") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Accept"] = 'application/json' request["X-Auth-Token"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"type\": \"radio_buttons\",\n \"required\": true,\n \"display_name\": \"Donation\",\n \"sort_order\": 0,\n \"option_values\": [\n {\n \"adjusters\": {\n \"price\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 5\n },\n \"weight\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 5\n },\n \"purchasing_disabled\": {\n \"status\": true,\n \"message\": \"string\"\n }\n },\n \"is_default\": false,\n \"label\": \"+5\",\n \"sort_order\": 0,\n \"value_data\": {}\n },\n {\n \"adjusters\": {\n \"price\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 10\n },\n \"weight\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 10\n },\n \"purchasing_disabled\": {\n \"status\": true,\n \"message\": \"string\"\n }\n },\n \"is_default\": false,\n \"label\": \"+10\",\n \"sort_order\": 0,\n \"value_data\": {}\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java Create a product modifier import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/1/modifiers") .header("Accept", "application/json") .header("X-Auth-Token", "") .header("Content-Type", "application/json") .body("{\n \"type\": \"radio_buttons\",\n \"required\": true,\n \"display_name\": \"Donation\",\n \"sort_order\": 0,\n \"option_values\": [\n {\n \"adjusters\": {\n \"price\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 5\n },\n \"weight\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 5\n },\n \"purchasing_disabled\": {\n \"status\": true,\n \"message\": \"string\"\n }\n },\n \"is_default\": false,\n \"label\": \"+5\",\n \"sort_order\": 0,\n \"value_data\": {}\n },\n {\n \"adjusters\": {\n \"price\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 10\n },\n \"weight\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 10\n },\n \"purchasing_disabled\": {\n \"status\": true,\n \"message\": \"string\"\n }\n },\n \"is_default\": false,\n \"label\": \"+10\",\n \"sort_order\": 0,\n \"value_data\": {}\n }\n ]\n}") .asString(); ``` ```php Create a product modifier request('POST', 'https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/1/modifiers', [ 'body' => '{ "type": "radio_buttons", "required": true, "display_name": "Donation", "sort_order": 0, "option_values": [ { "adjusters": { "price": { "adjuster": "relative", "adjuster_value": 5 }, "weight": { "adjuster": "relative", "adjuster_value": 5 }, "purchasing_disabled": { "status": true, "message": "string" } }, "is_default": false, "label": "+5", "sort_order": 0, "value_data": {} }, { "adjusters": { "price": { "adjuster": "relative", "adjuster_value": 10 }, "weight": { "adjuster": "relative", "adjuster_value": 10 }, "purchasing_disabled": { "status": true, "message": "string" } }, "is_default": false, "label": "+10", "sort_order": 0, "value_data": {} } ] }', 'headers' => [ 'Accept' => 'application/json', 'Content-Type' => 'application/json', 'X-Auth-Token' => '', ], ]); echo $response->getBody(); ``` ```csharp Create a product modifier using RestSharp; var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/1/modifiers"); var request = new RestRequest(Method.POST); request.AddHeader("Accept", "application/json"); request.AddHeader("X-Auth-Token", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"type\": \"radio_buttons\",\n \"required\": true,\n \"display_name\": \"Donation\",\n \"sort_order\": 0,\n \"option_values\": [\n {\n \"adjusters\": {\n \"price\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 5\n },\n \"weight\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 5\n },\n \"purchasing_disabled\": {\n \"status\": true,\n \"message\": \"string\"\n }\n },\n \"is_default\": false,\n \"label\": \"+5\",\n \"sort_order\": 0,\n \"value_data\": {}\n },\n {\n \"adjusters\": {\n \"price\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 10\n },\n \"weight\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 10\n },\n \"purchasing_disabled\": {\n \"status\": true,\n \"message\": \"string\"\n }\n },\n \"is_default\": false,\n \"label\": \"+10\",\n \"sort_order\": 0,\n \"value_data\": {}\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Create a product modifier import Foundation let headers = [ "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" ] let parameters = [ "type": "radio_buttons", "required": true, "display_name": "Donation", "sort_order": 0, "option_values": [ [ "adjusters": [ "price": [ "adjuster": "relative", "adjuster_value": 5 ], "weight": [ "adjuster": "relative", "adjuster_value": 5 ], "purchasing_disabled": [ "status": true, "message": "string" ] ], "is_default": false, "label": "+5", "sort_order": 0, "value_data": [] ], [ "adjusters": [ "price": [ "adjuster": "relative", "adjuster_value": 10 ], "weight": [ "adjuster": "relative", "adjuster_value": 10 ], "purchasing_disabled": [ "status": true, "message": "string" ] ], "is_default": false, "label": "+10", "sort_order": 0, "value_data": [] ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/1/modifiers")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```