Manage Shared Modifiers and Modifier Values
Shared Modifiers are modifiers that you can share among products in the Catalog. Shared modifiers help organize the Catalog and simplify store operations, saving time when managing a store.
In this guide, you will manage shared modifiers through the Catalog API. The guide also demonstrates how to manage modifier values for modifier types that have them.
The API allows you to create modifiers and see the number of products assigned to the modifier. However, assigning shared modifiers to products must be done through the control panel.
Prerequisites
To successfully complete the guide, verify that you have the following configured before you begin:
- A functioning BigCommerce store
- A store-level API account that contains the following OAuth scopes:
UI Name | Permission | Parameter | Description |
---|---|---|---|
Products | modify | store_v2_products | View and modify products, brands, categories, and other product information. |
Shared modifiers
Discover how to manage shared modifiers in the following sections.
Different modifier types have various config
fields and may have values
for you to create. You can find schemas for each type in the Create shared modifiers reference.
Create shared modifiers
Create shared modifiers in bulk for the Catalog. Send a request to the Create shared modifiers endpoint. The following example creates a checkbox modifier.
You can create modifier values when you create the modifier; however, you can also do so using the Create shared modifier values endpoint.
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-modifiers
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
[
{
"name": "prewashed!",
"storefront_name": "Prewashed",
"type": "checkbox",
"config": {
"checkbox_label": "Prewashed",
"checked_by_default": false
},
"required": true
}
]
Update shared modifiers
Update shared modifiers in bulk for the Catalog. Send a request to the Update shared modifiers endpoint. The following example updates a checkbox modifier.
You can update modifier values when you update the modifier; however, you can also do so using the Update shared modifier values endpoint.
PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-modifiers
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
[
{
"id": 41,
"name": "prewashed!",
"storefront_name": "Prewashed!",
"type": "checkbox",
"config": {
"checkbox_label": "Prewashed!",
"checked_by_default": true
},
"required": true
}
]
Get shared modifiers
Get shared modifiers for the Catalog. Send a request to the Get shared modifiers endpoint.
The following example retrieves all shared modifiers, but you can use a query parameter or the Get a shared modifier endpoint to retrieve a specific modifier.
The response returns the number of products assigned to the shared modifier.
GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-modifiers
X-Auth-Token: {{access_token}}
Accept: application/json
Delete shared modifiers
Delete shared modifiers for the Catalog by sending a request to the Delete shared modifiers endpoint. Use a query parameter to specify the ID(s) for the shared modifier(s) you wish to delete. The following example deletes the shared modifier that has an ID of 13.
DELETE https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-modifiers?id:in=13
X-Auth-Token: {{access_token}}
Accept: application/json
Shared modifier values
Discover how to manage modifier values for shared modifiers in the following sections.
Only multiple-choice types have values
for you to create and update. The Shared Options and Modifiers Overview explains which types are multiple choice.
Create shared modifier values
Create shared modifier values in bulk for an existing shared modifier. Send a request to the Create shared modifiers values endpoint. The following example adds an additional value to an existing dropdown shared modifier.
You can also create values when you create the shared modifier.
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-modifiers/{{modifier_id}}/values
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
[
{
"label": "XL",
"sort_order": 3
}
]
Update shared modifier values
Update modifier values in bulk for an existing shared modifier. Send a request to the Update shared modifier values endpoint. The following example updates values that belong to an existing shared modifier.
You can also update values when you update the entire shared modifier.
PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-modifiers/{{modifier_id}}/values
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
[
{
"id": 22,
"label": "Small",
"option_id": 18,
"sort_order": 0
},
{
"id": 23,
"label": "Medium",
"option_id": 18,
"sort_order": 1
},
{
"id": 24,
"label": "Large",
"option_id": 18,
"sort_order": 2
},
{
"id": 46,
"label": "Extra Large",
"option_id": 18,
"sort_order": 3
}
]
Get shared modifier values
Get the modifier values for a shared modifier. Send a request to the Get shared modifier values endpoint.
The following example retrieves all modifier values for a dropdown modifier, but you can use a query parameter or the Get a shared modifier value endpoint to retrieve a specific modifier value.
GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-modifiers/{{modifier_id}}/values
X-Auth-Token: {{access_token}}
Accept: application/json
Delete shared modifier values
Delete values for a shared modifier by sending a request to the Delete shared modifier values endpoint. Use a query parameter to specify the ID(s) for the value(s) you wish to delete. The following example deletes the modifier values that have an ID of 39 and 40.
DELETE https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-modifiers/{{modifier_id}}/values
X-Auth-Token: {{access_token}}
Accept: application/json
Resources
Shared modifiers reference
- Create shared modifiers
- Update shared modifiers
- Get shared modifiers
- Delete shared modifiers
- Get a shared modifier
Shared modifier values reference
- Create shared modifier values
- Update shared modifier values
- Get shared modifier values
- Delete shared modifier values
- Get a shared modifier value