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.

Example request: Create shared options

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.

Example request: Update shared options

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.

Example request: Get shared options

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.

Example request: Delete shared options

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.

Example request: Create shared option values

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.

Example request: Update shared option values

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.

Example request: Get shared option values

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.

Example request: Delete shared option values

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