Product Variant Options

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

Perform the following for product variant options:

Set global variant option information for the catalog. Channels inherit global information by default.
Create overrides for a channel locale using the overridesForLocale field. These override global store information.
Remove overrides for a channel locale

You can also set and remove information for shared variant options (opens in a new tab). 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 (opens in a new tab).

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

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json      
 
mutation ($input: SetProductOptionsInformationInput!) {
  product {
    setProductOptionsInformation (input: $input) {
      product {
        id
        options (first: 2) {
          edges {
            node {
              id
              displayName
              isShared
              values {
                id
                label
              }
            }
          }
        }
      }
    }
  }
}

GraphQL variables

{
  "input": {
    "productId": "bc/store/product/111",
    "data": {
      "options": [
        {
          "optionId": "bc/store/productOption/108",
          "data": {
            "dropdown": {
              "displayName": "Size US",
              "values": [
                {
                  "valueId": "bc/store/productOptionValue/68",
                  "label": "Small US"
                },
                {
                  "valueId": "bc/store/productOptionValue/69",
                  "label": "Medium US"
                },
                {
                  "valueId": "bc/store/productOptionValue/70",
                  "label": "Large US"
                }
              ]
            }
          }
        }
      ]
    }
  }
}

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

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json      
 
mutation ($input: SetProductOptionsInformationInput!) {
  product {
    setProductOptionsInformation (input: $input) {
      product {
        id
        options (first: 2) {
          edges {
            node {
              id
              overridesForLocale(
                localeContext: {
                  channelId: "bc/store/channel/2",
                  locale: "uk"
                }
              ) {
                displayName
                values {
                  id
                  label
                }
              }
            }
          }
        }
      }
    }
  }
}

GraphQL variables

{
  "input": {
    "productId": "bc/store/product/111",
    "localeContext": {
      "channelId": "bc/store/channel/2",
      "locale": "uk"
    },
    "data": {
      "options": [
        {
          "optionId": "bc/store/productOption/108",
          "data": {
            "dropdown": {
              "displayName": "Size UK",
              "values": [
                {
                  "valueId": "bc/store/productOptionValue/68",
                  "label": "Small UK"
                },
                {
                  "valueId": "bc/store/productOptionValue/69",
                  "label": "Medium UK"
                },
                {
                  "valueId": "bc/store/productOptionValue/70",
                  "label": "Large UK"
                } 
              ]
            }
          }
        }
      ]
    }
  }
}

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

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
mutation ($input: RemoveProductOptionsOverridesInput!) {
  product {
    removeProductOptionsOverrides (input: $input) {
      product {
        id
        options (first: 2) {
          edges {
            node {
              id
              displayName
              values {
                id
                label
              }
              overridesForLocale (localeContext: {channelId: "bc/store/channel/2", locale: "uk"}) {
                displayName
                values {
                  id
                  label
                }
              }
            }
          }
        }
      }
    }
  }
}

GraphQL variables

{
  "input": {
    "productId": "bc/store/product/111",
    "localeContext": { 
      "channelId": "bc/store/channel/2",
      "locale": "uk"
    },
    "data": {
      "options": [
        {
          "optionId": "bc/store/productOption/108",
          "data": {
            "dropdown": {
              "fields": ["DROPDOWN_PRODUCT_OPTION_DISPLAY_NAME_FIELD"],
              "values": {
                "ids": ["bc/store/productOptionValue/70"]
              }
            }
          }
        }
      ]
    }
  }
}

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

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json      
 
mutation ($input: SetSharedProductOptionsInformationInput!) {
  sharedProductOptions {
    setSharedProductOptionsInformation (input: $input) {
      sharedProductOptions {
        id
      }
    }
  }
}

GraphQL variables

{
  "input": {
    "data": {
      "options": [
        {
          "optionId": "bc/store/sharedProductOption/1",
          "data": {
            "dropdown": {
              "displayName": "Fabric",
              "values": [
                {
                  "valueId": "bc/store/sharedProductOptionValue/123",
                  "label": "Cotton"
                },
                {
                  "valueId": "bc/store/sharedProductOptionValue/124",
                  "label": "Polyester"
                }
              ]
            }
          }
        },
        {
          "optionId": "bc/store/sharedProductOption/4",
          "data": {
            "swatch": {
              "displayName": "Zipper color",
              "values": [
                {
                  "valueId": "bc/store/sharedProductOptionValue/129",
                  "label": "Orange"
                },
                {
                  "valueId": "bc/store/sharedProductOptionValue/130",
                  "label": "Green"
                }
              ]
            }
          }
        }
      ]
    }
  }
}

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

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json      
 
mutation ($input: SetSharedProductOptionsInformationInput!) {
  sharedProductOptions {
    setSharedProductOptionsInformation (input: $input) {
      sharedProductOptions {
        id
      }
    }
  }
}

GraphQL variables

{
  "input": {
    "localeContext": {
      "channelId": "bc/store/channel/2",
      "locale": "uk"
    },
    "data": {
      "options": [
        {
          "optionId": "bc/store/sharedProductOption/1",
          "data": {
            "dropdown": {
              "displayName": "Fabric material",
              "values": [
                {
                  "valueId": "bc/store/sharedProductOptionValue/123",
                  "label": "Linen"
                },
                {
                  "valueId": "bc/store/sharedProductOptionValue/124",
                  "label": "Nylon"
                }
              ]
            }
          }
        },
        {
          "optionId": "bc/store/sharedProductOption/4",
          "data": {
            "swatch": {
              "displayName": "Color of zipper",
              "values": [
                {
                  "valueId": "bc/store/sharedProductOptionValue/129",
                  "label": "Black"
                },
                {
                  "valueId": "bc/store/sharedProductOptionValue/130",
                  "label": "Brown"
                }
              ]
            }
          }
        }
      ]
    }
  }
}

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

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
mutation ($input: RemoveSharedProductOptionsOverridesInput!) {
  sharedProductOptions {
    removeSharedProductOptionsOverrides (input: $input) {
      sharedProductOptions {
        id
      }
    }
  }
}

GraphQL variables

{
  "input": {
    "localeContext": {
      "channelId": "bc/store/channel/2",
      "locale": "uk"
    },
    "data": {
      "options": [
        {
          "optionId": "bc/store/sharedProductOption/2",
          "data": {
            "radioButtons": {
              "fields": ["RADIO_BUTTONS_SHARED_PRODUCT_OPTION_DISPLAY_NAME_FIELD"],
              "values": {
                "ids": ["bc/store/sharedProductOptionValue/125", "bc/store/sharedProductOptionValue/126"]
              }
            }
          }
        }
      ]
    }
  }
}

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

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
query {
  store {
    product(id: "bc/store/product/111") {
      id
      options (first: 3) {
        edges {
          node {
            id
            displayName
            isShared
            values {
              id
              label
              isDefault
            }
            overridesForLocale(
              localeContext: { channelId: "bc/store/channel/2", locale: "uk"}
            ) {
              displayName
              values {
                id
                label
              }
            }
          }
        }
      }
    }
  }
}

Did you find what you were looking for?

Product SEO information Product modifier options