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.

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:

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 Options and Modifiers Overview
• Catalog API Reference- Shared Options and Modifiers

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