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:

UI NamePermissionParameterDescription
Productsmodifystore_v2_productsView 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.

Example request: Create shared modifiers
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.

Example request: Update shared modifiers
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.

Example request: Get shared modifiers
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.

Example request: Delete shared modifiers
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.

Example request: Create shared modifier values
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.

Example request: Update shared modifier values
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.

Example request: Get shared modifier values
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.

Example request: Delete shared modifier values
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

Shared modifier values reference

Did you find what you were looking for?