> 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 Value POST https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products/{product_id}/modifiers/{modifier_id}/values Content-Type: application/json Creates a modifier value. **Read-Only Fields** * is_default **Setting an option value image** `adjusters.image_url` is read-only on this endpoint. To attach the image shown on the storefront for the value, upload it via [Create Product Modifier Image](/developer/api-reference/rest/admin/catalog/product-modifiers/images/create-product-modifier-image) after creating the value. > `is_default` is derived from the parent modifier configuration and cannot be set on individual values. To change which value is the default, use [Update Product Modifier](/developer/api-reference/rest/admin/catalog/product-modifiers/update-product-modifier) and include the full `option_values` array with the desired `is_default` flags. Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/catalog/product-modifiers/values/create-product-modifier-value ## 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. - `modifier_id` (integer, required) — The ID of the product modifier. - `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 an object. - `label` (string, required) — The text display identifying the value on the storefront. Required in a /POST. - `sort_order` (integer, required) — The order in which the value will be displayed on the product page. Required in a /POST. - `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. Read-only on this endpoint; use [Update Product Modifier](/developer/api-reference/rest/admin/catalog/product-modifiers/update-product-modifier) with the full `option_values` array to change the default. - `value_data` (CatalogProductsProductIdModifiersModifierIdValuesPostRequestBodyContentApplicationJsonSchemaValueData, optional) — 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 hexadecimal 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. - `adjusters` (CatalogProductsProductIdModifiersModifierIdValuesPostRequestBodyContentApplicationJsonSchemaAdjusters, optional) ## Response ### 200 OK - `data` (productModifierOptionValue_Full, optional) — Product modifier `option_value`. - `meta` (metaEmpty_Full, optional) — Response metadata. ## Errors ### 422 Unprocessable Entity Error The `ModifierValue` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - `errors` (CatalogProductsProductIdModifiersModifierIdValuesPostResponsesContentApplicationJsonSchemaErrors, 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 ### CatalogProductsProductIdModifiersModifierIdValuesPostRequestBodyContentApplicationJsonSchemaValueData 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 hexadecimal 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. ### CatalogProductsProductIdModifiersModifierIdValuesPostRequestBodyContentApplicationJsonSchemaAdjusters - `price` (CatalogProductsProductIdModifiersModifierIdValuesPostRequestBodyContentApplicationJsonSchemaAdjustersPrice, optional) — Adjuster for Complex Rules. - `weight` (CatalogProductsProductIdModifiersModifierIdValuesPostRequestBodyContentApplicationJsonSchemaAdjustersWeight, optional) — Adjuster for Complex Rules. - `image_url` (string, optional) — The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - `purchasing_disabled` (CatalogProductsProductIdModifiersModifierIdValuesPostRequestBodyContentApplicationJsonSchemaAdjustersPurchasingDisabled, optional) ### 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. ### metaEmpty_Full Response metadata. ### CatalogProductsProductIdModifiersModifierIdValuesPostResponsesContentApplicationJsonSchemaErrors ### CatalogProductsProductIdModifiersModifierIdValuesPostRequestBodyContentApplicationJsonSchemaAdjustersPrice 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. ### CatalogProductsProductIdModifiersModifierIdValuesPostRequestBodyContentApplicationJsonSchemaAdjustersWeight 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. ### CatalogProductsProductIdModifiersModifierIdValuesPostRequestBodyContentApplicationJsonSchemaAdjustersPurchasingDisabled - `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`. ### 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. ### 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 { "label": "Yes", "sort_order": 0, "is_default": false, "adjusters": { "price": { "adjuster": "relative", "adjuster_value": 5 } } } ``` **Response** ```json { "data": { "adjusters": { "price": { "adjuster": "relative", "adjuster_value": 5 }, "weight": {}, "image_url": "", "purchasing_disabled": { "status": false, "message": "" } }, "id": 190, "is_default": false, "label": "Yes", "option_id": 222, "sort_order": 0, "value_data": {} }, "meta": {} } ``` **SDK Code** ```python Create a product modifier value import requests url = "https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/1/modifiers/1/values" payload = { "label": "Yes", "sort_order": 0, "is_default": False, "adjusters": { "price": { "adjuster": "relative", "adjuster_value": 5 } } } 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 value const url = 'https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/1/modifiers/1/values'; const options = { method: 'POST', headers: { Accept: 'application/json', 'X-Auth-Token': '', 'Content-Type': 'application/json' }, body: '{"label":"Yes","sort_order":0,"is_default":false,"adjusters":{"price":{"adjuster":"relative","adjuster_value":5}}}' }; 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 value package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/1/modifiers/1/values" payload := strings.NewReader("{\n \"label\": \"Yes\",\n \"sort_order\": 0,\n \"is_default\": false,\n \"adjusters\": {\n \"price\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 5\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 value require 'uri' require 'net/http' url = URI("https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/1/modifiers/1/values") 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 \"label\": \"Yes\",\n \"sort_order\": 0,\n \"is_default\": false,\n \"adjusters\": {\n \"price\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 5\n }\n }\n}" response = http.request(request) puts response.read_body ``` ```java Create a product modifier value 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/1/values") .header("Accept", "application/json") .header("X-Auth-Token", "") .header("Content-Type", "application/json") .body("{\n \"label\": \"Yes\",\n \"sort_order\": 0,\n \"is_default\": false,\n \"adjusters\": {\n \"price\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 5\n }\n }\n}") .asString(); ``` ```php Create a product modifier value request('POST', 'https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/1/modifiers/1/values', [ 'body' => '{ "label": "Yes", "sort_order": 0, "is_default": false, "adjusters": { "price": { "adjuster": "relative", "adjuster_value": 5 } } }', 'headers' => [ 'Accept' => 'application/json', 'Content-Type' => 'application/json', 'X-Auth-Token' => '', ], ]); echo $response->getBody(); ``` ```csharp Create a product modifier value using RestSharp; var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/catalog/products/1/modifiers/1/values"); 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 \"label\": \"Yes\",\n \"sort_order\": 0,\n \"is_default\": false,\n \"adjusters\": {\n \"price\": {\n \"adjuster\": \"relative\",\n \"adjuster_value\": 5\n }\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Create a product modifier value import Foundation let headers = [ "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" ] let parameters = [ "label": "Yes", "sort_order": 0, "is_default": false, "adjusters": ["price": [ "adjuster": "relative", "adjuster_value": 5 ]] ] 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/1/values")! 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() ```