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 (opens in a new tab).
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:
# This example retrieves 1 variant.
# Specify multiple variant entityIds to retrieve multiple variants.
query {
site {
product (entityId: 113) {
variants (entityIds: [98]) {
edges {
node {
# fields on the Variant object type
}
}
}
}
}
}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:
# This query retrieves one variant.
query {
site {
product (variantEntityId: 27098) {
# fields on the Product object type
}
}
}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:
query {
site {
product (entityId: 113) {
variants (entityIds: [127]) {
edges {
node {
id
entityId
sku
upc
mpn
}
}
}
}
}
}Get variant prices and dimensions
Query the prices and dimensions for variants. The following query retrieves prices and dimensions for the specified variant:
# This query uses fragments. For more, see https://graphql.org/learn/queries#fragments.
query {
site {
product (entityId: 113) {
variants (entityIds: [98]) {
edges {
node {
prices {
price {
...PriceFields
}
salePrice {
...PriceFields
}
basePrice {
...PriceFields
}
retailPrice {
...PriceFields
}
}
width {
...DimensionFields
}
height {
...DimensionFields
}
depth {
...DimensionFields
}
weight {
...DimensionFields
}
}
}
}
}
}
}
# fields on the Money object type
fragment PriceFields on Money {
value
currencyCode
}
# fields on the Measurement object type
fragment DimensionFields on Measurement {
value
unit
}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) (opens in a new tab).
The following example shows how to get the first two variant options that are associated with the base product for the specified variant:
# This query uses interfaces. For more, see https://graphql.org/learn/schema#interfaces.
query {
site {
product (entityId: 113) {
variants (entityIds: [127]) {
edges {
node {
productOptions (first: 2) {
edges {
node {
... on MultipleChoiceOption {
entityId
displayName
isRequired
isVariantOption
displayStyle
}
}
}
}
}
}
}
}
}
}Get variant option values
All variant options are multiple choice (Help Center) (opens in a new tab). 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 (opens in a new tab) documentation.
# 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.
# This query uses interfaces. For more, see https://graphql.org/learn/schema#interfaces.
query {
site {
product (entityId: 113) {
variants (entityIds: [127]) {
edges {
node {
productOptions (first: 2) {
edges {
node {
# fields all muliple choice options include
... on MultipleChoiceOption {
values {
edges {
node {
entityId
label
isDefault
# additional fields for swatch options
... on SwatchOptionValue {
hexColors
imageUrl (width: 2)
}
}
}
}
}
}
}
}
}
}
}
}
}
}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.
query {
site {
product(entityId: 113) {
variants(entityIds: [127]) {
edges {
node {
options (first: 2) {
edges {
node {
entityId
displayName
isRequired
values {
edges {
node {
entityId
label
}
}
}
}
}
}
}
}
}
}
}
}
Get variant images
Query the images for variants. The following query retrieves the image for the specified variant:
query {
site {
product (entityId: 113) {
variants (entityIds: [127]) {
edges {
node {
defaultImage {
url (width: 1)
urlOriginal
altText
isDefault
}
}
}
}
}
}
}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:
query {
site {
product (entityId: 113) {
variants (entityIds: [127]) {
edges {
node {
metafields (first: 1 namespace: "Warehouse Locations") {
edges {
node {
id
entityId
key
value
}
}
}
}
}
}
}
}
}Resources
GraphQL documentation
- GraphQL Storefront API overview
- Guide to Working with products
- GraphQL Storefront API explorer (opens in a new tab)
- GraphQL Storefront API playground (opens in a new tab)
- GraphQL language (graphql.org) (opens in a new tab)
- GraphQL schema and types (graphql.org) (opens in a new tab)
REST API endpoints
- Catalog API - Variants overview
- Catalog API - Update product variant metafields endpoint
- Catalog API - Get variant metafields endpoint
- Catalog API - Get product metafields endpoint