Manage Shared Options and Option Values
Shared Option are options that you can share among products in the Catalog. Shared options help organize the Catalog and simplify store operations, saving time when managing a store.
In this guide, you will manage shared options through the Catalog API.
The API allows you to create the options and see products assigned to the option. However, assigning shared options 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 options
Discover how to manage shared options in the following sections.
Create shared options
Create shared options in bulk for the Catalog. Send a request to the Create shared options endpoint. The following example creates a swatch shared option with two option values.
You can create option values when you create the shared option; however, you can also use the Create shared option values endpoint.
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-product-options
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
[
{
"name": "color",
"storefront_name": "Sweater Color",
"type": "swatch",
"values": [
{
"label": "Dual color",
"sort_order": 0,
"value_data": { // Only swatch types use the `value_data` field
"colors": [
"#E38535",
"#DFB713"
]
},
"is_default": true
},
{
"label": "Single color",
"sort_order": 1,
"value_data": {
"colors": [
"#E38535"
]
},
"is_default": false
}
]
}
]
Update shared options
Update shared options in bulk for the Catalog. Send a request to the Update shared options endpoint. The following example updates a swatch shared option.
You can update option values when you update the shared option; however, you can also do so using the Update shared option values endpoint.
PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-product-options
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
[
{
"id": 34,
"name": "color",
"storefront_name": "Sweater Color",
"type": "swatch",
"values": [
{
"id": 37,
"label": "Dual color",
"sort_order": 0,
"value_data": { // Only swatch types use the `value_data` field
"colors": [
"#E32222",
"#DFB713"
]
},
"is_default": true
},
{
"id": 38,
"label": "Single color",
"sort_order": 1,
"value_data": {
"colors": [
"#E38535"
]
},
"is_default": false
}
]
}
]
Get shared options
Get shared options for the Catalog. Send a request to the Get shared options endpoint.
The following example retrieves all shared options, but you can use a query parameter or the Get a shared option endpoint to retrieve a specific option.
The response returns the products assigned to the shared option.
GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-product-options
X-Auth-Token: {{access_token}}
Accept: application/json
Delete shared options
Delete shared options for the Catalog by sending a request to the Delete shared options endpoint. Use a query parameter to specify the ID(s) for the shared option(s) you wish to delete. The following example deletes the shared option that has an ID of 1.
DELETE https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-product-options?id:in=1
X-Auth-Token: {{access_token}}
Accept: application/json
Shared option values
Discover how to manage option values for shared options in the following sections.
Create shared option values
Create shared options values in bulk for an existing shared option. Send a request to the Create shared options values endpoint. The following example adds an additional value to the existing swatch shared option.
You can also create values when you create the shared option.
POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-product-options/{{option_id}}/values
Content-Type: application/json
Accept: application/json
[
{
"label": "Triple color",
"sort_order": 2,
"value_data": { // Only swatch types use the `value_data` field
"colors": [
"#E32222",
"#DFB713",
"#314344"
]
}
}
]
Update shared option values
Update options values in bulk for an existing shared option. Send a request to the Update shared options values endpoint. The following example updates values that belong to an existing shared option.
You can also update values when you update the entire shared option.
PUT https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-product-options/{{option_id}}/values
X-Auth-Token: {{access_token}}
Content-Type: application/json
Accept: application/json
[
{
"id": 37,
"label": "Dual color",
"sort_order": 1,
"value_data": { // Only swatch types use the `value_data` field
"colors": [
"#E32223",
"#DFB714"
]
}
},
{
"id": 39,
"label": "Triple color",
"sort_order": 2,
"value_data": {
"colors": [
"#E32223",
"#DFB714",
"#314345"
]
}
}
]
Get shared option values
Get the option values for a shared option. Send a request to the Get shared option values endpoint.
The following example retrieves all values for a swatch option, but you can use a query parameter or the Get a shared option value endpoint to retrieve a specific option value.
GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-product-options/{{option_id}}/values
X-Auth-Token: {{access_token}}
Accept: application/json
Delete shared option values
Delete values for a shared option by sending a request to the Delete shared options values endpoint. Use a query parameter to specify the ID(s) for the value(s) you wish to delete. The following example deletes the option values that have an ID of 39 and 40.
DELETE https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/shared-product-options/{{option_id}}/values?id:in=39,40
X-Auth-Token: {{access_token}}
Accept: application/json
Resources
Shared options reference
- Create shared options
- Update shared options
- Get shared options
- Delete shared options
- Get a shared option
Shared option values reference
- Create shared option values
- Update shared option values
- Get shared option values
- Delete shared option values
- Get a shared option value