DocsStorefrontGuidesGraphQL StorefrontProducts & Catalog

Variants

GraphQL Storefront API

Guide to Working with Product Variants

BigCommerce’s GraphQL Storefront API lets frontend developers retrieve variants from a store. These built-in capabilities also allow developers to customize their hosted or headless storefronts with variant information.

The GraphQL Storefront API lets you retrieve the following variant attributes and more:

  • Price information in a store’s transacting currency
  • Variant options associated with a variant, along with their values
  • Variant metafields that have storefront access

You can access these attributes if a merchant makes the product visible on storefronts.

This guide walks you through how to retrieve information for a variant. To retrieve information for the base product, see Guide to Working with Products. For full schema documentation, see the GraphQL Storefront Playground.

Get a variant

Get a variant with the variants field

Query a variant by specifying a variant identifier. For instance, use the variant entityId or optionValueId for the variants field as shown here:

Get a variant using the variant entity ID
1# This example retrieves 1 variant.
2# Specify multiple variant entityIds to retrieve multiple variants.
3
4query {
5  site {
6    product (entityId: 113) {         
7      variants (entityIds: [98]) {    
8        edges {
9          node {
10            # fields on the Variant object type
11          }
12        }
13      }
14    }
15  }
16}

Query all variants by omitting an argument for variants.

Get a variant with the product field

Query a variant by specifying a variant identifier for the product field. Use the variant’s entity ID, variant option value entity IDs, or variant SKU:

Get a variant using the variant entity ID
1# This query retrieves one variant. 
2
3query {
4  site {
5    product (variantEntityId: 27098) {
6      # fields on the Product object type  
7    }
8  }
9}

Specifying a variant identifier for the product field returns variant information overlaid on the Product object. For example, if the variant has a different image, dimensions, SKU, or price, than the product, the variant’s information will be returned. This allows you to directly query a variant.

Get variant identifiers

Query identifying information for variants by using the following query:

Example query: Get basic information for a variant
1query {
2  site {
3    product (entityId: 113) {
4      variants (entityIds: [127]) {
5        edges {
6          node {
7            id
8            entityId
9            sku  
10            upc
11            mpn
12          }
13        }
14      }   
15    }
16  }
17}

Get variant prices and dimensions

Query the prices and dimensions for variants. The following query retrieves prices and dimensions for the specified variant:

Example query: Get prices and dimensions for a variant
1# This query uses fragments. For more, see https://graphql.org/learn/queries#fragments.
2
3query {
4  site {
5    product (entityId: 113) {
6      variants (entityIds: [98]) {
7        edges {
8          node {
9            prices {
10              price {
11                ...PriceFields
12              }
13              salePrice {
14                ...PriceFields
15              }
16              basePrice {
17                ...PriceFields
18              }
19              retailPrice {
20                ...PriceFields
21              }
22            }
23            width {
24              ...DimensionFields
25            }
26            height {
27              ...DimensionFields
28            }
29            depth {
30              ...DimensionFields
31            }
32            weight {
33              ...DimensionFields
34            }
35          }
36        }
37      }
38    }
39  }
40}
41      
42# fields on the Money object type
43fragment PriceFields on Money {               
44  value
45  currencyCode
46}
47
48# fields on the Measurement object type
49fragment DimensionFields on Measurement {     
50  value
51  unit
52}

Get variant options and variant option values

Query variant options, and their associated values, that are available with variants.

Get variant options

All variant options are multiple choice (Help Center).

The following example shows how to get the first two variant options that are associated with the base product for the specified variant:

Example query: Get variant options for a variant
1# This query uses interfaces. For more, see https://graphql.org/learn/schema#interfaces.
2
3query {
4  site {
5    product (entityId: 113) {
6      variants (entityIds: [127]) {
7        edges {
8          node {
9            productOptions (first: 2) {
10              edges {
11                node {
12                  ... on MultipleChoiceOption { 
13                    entityId                              
14                    displayName
15                    isRequired
16                    isVariantOption
17                    displayStyle
18                  }
19                }
20              }
21            }
22          }
23        }
24      }
25    }
26  }
27}

Get variant option values

All variant options are multiple choice (Help Center). With variant options, you get to retrieve the multiple choice values, or the variant option values, associated with a variant.

Multiple choice values are made up of various types, like swatch or radio buttons. Each type of multiple choice value has a specific schema that implements the CatalogProductOptionValue interface (meaning you can retrieve the common fields from CatalogProductOptionValue for any type of multiple choice value). For more on interfaces, see the GraphQL Schema and Types- Interfaces documentation.

CatalogProductOptionValue interface
# Fields common among multiple choice values 
interface CatalogProductOptionValue {
  entityId: Int!
  label: String!
  isDefault: Boolean!`
}

The following example retrieves variant option values for the specified variant. In the response, all multiple choice values include queried fields from the CatalogProductOptionValue interface, and those that are swatch types include additional fields. The example query retrieves only the first two variant options associated with the base product.

Example query: Get variant option values for a variant
1# This query uses interfaces. For more, see https://graphql.org/learn/schema#interfaces.
2
3query {
4  site {
5    product (entityId: 113) {
6      variants (entityIds: [127]) {
7        edges {
8          node {
9            productOptions (first: 2) {
10              edges {
11                node {
12                  
13                  # fields all muliple choice options include
14                  ... on MultipleChoiceOption {           
15                    values {
16                      edges {
17                        node {
18                          entityId
19                          label
20                          isDefault
21                          
22                          # additional fields for swatch options
23                          ... on SwatchOptionValue {      
24                            hexColors
25                            imageUrl (width: 2)
26                          }
27                        }
28                      }
29                    }
30                  }
31                }
32              }
33            }
34          }
35        }
36      }
37    }
38  }
39}

Retrieve variant option values using the options field. The following query retrieves the variant option values that are associated with the specified variant. The example query retrieves only the first two variant options associated with the base product.

Example query: Get variant option values for a variant
1query {
2  site {
3    product(entityId: 113) {
4      variants(entityIds: [127]) {
5        edges {
6          node {
7            options (first: 2) {
8              edges {
9                node {
10                  entityId
11                  displayName
12                  isRequired
13                  values {
14                    edges {
15                      node {
16                        entityId
17                        label
18                      }
19                    }
20                  }
21                }
22              }
23            }
24          }
25        }
26      }
27    }
28  }
29}

Get variant images

Query the images for variants. The following query retrieves the image for the specified variant:

Example query: Get images for a variant
1query {
2  site {
3    product (entityId: 113) {
4      variants (entityIds: [127]) {
5        edges {
6          node {
7            defaultImage {
8              url (width: 1)
9              urlOriginal
10              altText
11              isDefault
12            } 
13          }
14        }
15      }  
16    }
17  }
18}

Get variant metafields

Query variant metafields by specifying the namespace for the variant metafields. The API returns only metafields that have storefront permissions. Permissions must be set to write_and_sf_access or read_and_sf_access. To set permissions, use the Update product variant metafields endpoint.

Variant versus product metafields

The query returns only variant metafields. To retrieve product metafields, see Get product metafields.

The following query retrieves the first variant metafield for the specified variant:

Example query: Get variant metafields for a variant
1query {
2  site {
3    product (entityId: 113) {
4      variants (entityIds: [127]) {
5        edges {
6          node {
7            metafields (first: 1 namespace: "Warehouse Locations") {
8              edges {
9                node {
10                  id
11                  entityId
12                  key
13                  value
14                }
15              }
16            }  	 
17          }
18        }
19      }
20    }
21  }
22}

Resources

GraphQL documentation

REST API endpoints

Support articles