AdminCatalog and InventoryMSF International Enhancements

Product Variant Options

International Enhancements for Multi-Storefront

This feature is currently available for Enterprise stores and Partner Sandboxes. If the feature is not working as expected, please contact technical support, as the feature likely needs to be enabled for the individual store. To become an enterprise customer, contact your BigCommerce Customer Service Manager or our support team.

Using the Catalog features of the Admin API, you can set and query information about a product variant option, such as option name and values.

Perform the following for product variant options:

You can also set and remove information for shared variant options. The changes affect all products that you assign to the shared variant option. Querying variant options returns all variant options, including shared ones.

For a full schema, see the GraphQL Admin API reference.

Input fields

Setting or removing information requires that you specify ID fields in the input. For more information on how to specify ID fields, see Input fields.

Set variant options

Set information about a product variant option for a store or a locale within a storefront channel.

The following mutations let you set the name and values for existing variant options. You must first create the variant option for the product through the control panel or the REST Create a product variant option endpoint.

The responses may include all variant options, including those that are shared. However, to set shared variant options, use the mutations in Set shared variant options.

Set variant options at the global level

The following example sets the store’s global product variant option information, from which channels inherit by default. You can set the name and values for existing variant options.

Example mutation: Set product variant options at the global level
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2X-Auth-Token: {{ACCESS_TOKEN}}
3Content-Type: application/json
4Accept: application/json      
5
6mutation ($input: SetProductOptionsInformationInput!) {
7  product {
8    setProductOptionsInformation (input: $input) {
9      product {
10        id
11        options (first: 2) {
12          edges {
13            node {
14              id
15              displayName
16              isShared
17              values {
18                id
19                label
20              }
21            }
22          }
23        }
24      }
25    }
26  }
27}
GraphQL variables
1{
2  "input": {
3    "productId": "bc/store/product/111",
4    "data": {
5      "options": [
6        {
7          "optionId": "bc/store/productOption/108",
8          "data": {
9            "dropdown": {
10              "displayName": "Size US",
11              "values": [
12                {
13                  "valueId": "bc/store/productOptionValue/68",
14                  "label": "Small US"
15                },
16                {
17                  "valueId": "bc/store/productOptionValue/69",
18                  "label": "Medium US"
19                },
20                {
21                  "valueId": "bc/store/productOptionValue/70",
22                  "label": "Large US"
23                }
24              ]
25            }
26          }
27        }
28      ]
29    }
30  }
31}

Set variant options for a locale

The following example sets product variant option information for the locale within the specified storefront channel. These override global store information. You can set the name and values for existing variant options.

Example mutation: Set product variant options for a locale
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2X-Auth-Token: {{ACCESS_TOKEN}}
3Content-Type: application/json
4Accept: application/json      
5
6mutation ($input: SetProductOptionsInformationInput!) {
7  product {
8    setProductOptionsInformation (input: $input) {
9      product {
10        id
11        options (first: 2) {
12          edges {
13            node {
14              id
15              overridesForLocale(
16                localeContext: {
17                  channelId: "bc/store/channel/2",
18                  locale: "uk"
19                }
20              ) {
21                displayName
22                values {
23                  id
24                  label
25                }
26              }
27            }
28          }
29        }
30      }
31    }
32  }
33}
GraphQL variables
1{
2  "input": {
3    "productId": "bc/store/product/111",
4    "localeContext": {
5      "channelId": "bc/store/channel/2",
6      "locale": "uk"
7    },
8    "data": {
9      "options": [
10        {
11          "optionId": "bc/store/productOption/108",
12          "data": {
13            "dropdown": {
14              "displayName": "Size UK",
15              "values": [
16                {
17                  "valueId": "bc/store/productOptionValue/68",
18                  "label": "Small UK"
19                },
20                {
21                  "valueId": "bc/store/productOptionValue/69",
22                  "label": "Medium UK"
23                },
24                {
25                  "valueId": "bc/store/productOptionValue/70",
26                  "label": "Large UK"
27                } 
28              ]
29            }
30          }
31        }
32      ]
33    }
34  }
35}

Remove variant options for a locale

The following example removes product variant option information for the locale within the specified storefront channel.

Example mutation: Remove product variant options for a locale
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2X-Auth-Token: {{ACCESS_TOKEN}}
3Content-Type: application/json
4Accept: application/json
5
6mutation ($input: RemoveProductOptionsOverridesInput!) {
7  product {
8    removeProductOptionsOverrides (input: $input) {
9      product {
10        id
11        options (first: 2) {
12          edges {
13            node {
14              id
15              displayName
16              values {
17                id
18                label
19              }
20              overridesForLocale (localeContext: {channelId: "bc/store/channel/2", locale: "uk"}) {
21                displayName
22                values {
23                  id
24                  label
25                }
26              }
27            }
28          }
29        }
30      }
31    }
32  }
33}
GraphQL variables
1{
2  "input": {
3    "productId": "bc/store/product/111",
4    "localeContext": { 
5      "channelId": "bc/store/channel/2",
6      "locale": "uk"
7    },
8    "data": {
9      "options": [
10        {
11          "optionId": "bc/store/productOption/108",
12          "data": {
13            "dropdown": {
14              "fields": ["DROPDOWN_PRODUCT_OPTION_DISPLAY_NAME_FIELD"],
15              "values": {
16                "ids": ["bc/store/productOptionValue/70"]
17              }
18            }
19          }
20        }
21      ]
22    }
23  }
24}

Set shared variant options

You can set information about a shared variant option for a store or a locale within a storefront channel. You must first create the shared variant options through the control panel. Changing a shared variant option affects all products that you assign to the shared variant option. You cannot customize shared variant options on a product level.

The following mutations let you set the name and values for existing shared variant options.

Set shared variant options at the global level

The following example sets global shared variant option information for the store, from which channels inherit by default. You can set the name and values for existing variant options.

Example mutation: Set shared variant options at the global level
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2X-Auth-Token: {{ACCESS_TOKEN}}
3Content-Type: application/json
4Accept: application/json      
5
6mutation ($input: SetSharedProductOptionsInformationInput!) {
7  sharedProductOptions {
8    setSharedProductOptionsInformation (input: $input) {
9      sharedProductOptions {
10        id
11      }
12    }
13  }
14}
GraphQL variables
1{
2  "input": {
3    "data": {
4      "options": [
5        {
6          "optionId": "bc/store/sharedProductOption/1",
7          "data": {
8            "dropdown": {
9              "displayName": "Fabric",
10              "values": [
11                {
12                  "valueId": "bc/store/sharedProductOptionValue/123",
13                  "label": "Cotton"
14                },
15                {
16                  "valueId": "bc/store/sharedProductOptionValue/124",
17                  "label": "Polyester"
18                }
19              ]
20            }
21          }
22        },
23        {
24          "optionId": "bc/store/sharedProductOption/4",
25          "data": {
26            "swatch": {
27              "displayName": "Zipper color",
28              "values": [
29                {
30                  "valueId": "bc/store/sharedProductOptionValue/129",
31                  "label": "Orange"
32                },
33                {
34                  "valueId": "bc/store/sharedProductOptionValue/130",
35                  "label": "Green"
36                }
37              ]
38            }
39          }
40        }
41      ]
42    }
43  }
44}

Set shared variant options for a locale

The following example sets shared variant option information for the locale within the specified storefront channel. These override global store information. You can set the name and values for existing variant options.

Example mutation: Set shared variant options for a locale
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2X-Auth-Token: {{ACCESS_TOKEN}}
3Content-Type: application/json
4Accept: application/json      
5
6mutation ($input: SetSharedProductOptionsInformationInput!) {
7  sharedProductOptions {
8    setSharedProductOptionsInformation (input: $input) {
9      sharedProductOptions {
10        id
11      }
12    }
13  }
14}
GraphQL variables
1{
2  "input": {
3    "localeContext": {
4      "channelId": "bc/store/channel/2",
5      "locale": "uk"
6    },
7    "data": {
8      "options": [
9        {
10          "optionId": "bc/store/sharedProductOption/1",
11          "data": {
12            "dropdown": {
13              "displayName": "Fabric material",
14              "values": [
15                {
16                  "valueId": "bc/store/sharedProductOptionValue/123",
17                  "label": "Linen"
18                },
19                {
20                  "valueId": "bc/store/sharedProductOptionValue/124",
21                  "label": "Nylon"
22                }
23              ]
24            }
25          }
26        },
27        {
28          "optionId": "bc/store/sharedProductOption/4",
29          "data": {
30            "swatch": {
31              "displayName": "Color of zipper",
32              "values": [
33                {
34                  "valueId": "bc/store/sharedProductOptionValue/129",
35                  "label": "Black"
36                },
37                {
38                  "valueId": "bc/store/sharedProductOptionValue/130",
39                  "label": "Brown"
40                }
41              ]
42            }
43          }
44        }
45      ]
46    }
47  }
48}

Remove shared variant options for a locale

The following example removes shared variant option information for the locale within the specified storefront channel.

Example mutation: Remove shared variant options for a locale
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2X-Auth-Token: {{ACCESS_TOKEN}}
3Content-Type: application/json
4Accept: application/json
5
6mutation ($input: RemoveSharedProductOptionsOverridesInput!) {
7  sharedProductOptions {
8    removeSharedProductOptionsOverrides (input: $input) {
9      sharedProductOptions {
10        id
11      }
12    }
13  }
14}
GraphQL variables
1{
2  "input": {
3    "localeContext": {
4      "channelId": "bc/store/channel/2",
5      "locale": "uk"
6    },
7    "data": {
8      "options": [
9        {
10          "optionId": "bc/store/sharedProductOption/2",
11          "data": {
12            "radioButtons": {
13              "fields": ["RADIO_BUTTONS_SHARED_PRODUCT_OPTION_DISPLAY_NAME_FIELD"],
14              "values": {
15                "ids": ["bc/store/sharedProductOptionValue/125", "bc/store/sharedProductOptionValue/126"]
16              }
17            }
18          }
19        }
20      ]
21    }
22  }
23}

Query variant options

The following example retrieves variant information. You can retrieve global information for the store and overrides for the locale within the specified storefront channel. The query returns all variant options, including those that are shared.

Example query: Get variant options
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2X-Auth-Token: {{ACCESS_TOKEN}}
3Content-Type: application/json
4Accept: application/json
5
6query {
7  store {
8    product(id: "bc/store/product/111") {
9      id
10      options (first: 3) {
11        edges {
12          node {
13            id
14            displayName
15            isShared
16            values {
17              id
18              label
19              isDefault
20            }
21            overridesForLocale(
22              localeContext: { channelId: "bc/store/channel/2", locale: "uk"}
23            ) {
24              displayName
25              values {
26                id
27                label
28              }
29            }
30          }
31        }
32      }
33    }
34  }
35}