Products

GraphQL Storefront API

Guide to Working with Products

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

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

Price information in a store’s transacting currency
Product options associated with a product, both variant and modifier options
Product metafields that have storefront access

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

This guide walks you through the process of retrieving information for a product. If your product has variants, see Guide to Working with Product Variants on how to retrieve variant information. For full schema documentation, see the GraphQL Storefront Playground.

International Enhancements for Multi-Storefront allows some product features to have overrides in a storefront channel locale. For these features, the GraphQL Storefront API can return the global store value that the storefront inherits, or the override for the channel’s locale, depending on storefront settings. For a full list of product fields, see the International Enhancements for Multi-Storefront overview.

Get a Product

Get a product with the product field

You can query a product by using the product field and specifying a product identifier, for example, the product entityId.

Get a product with the product field

# This query retrieves one product.
query {
  site {
    product (entityId: 111) {
      # fields on the Product object type
    }
  }
}

Get a product with the product field

# This query retrieves two products.
# This query uses aliases and fragments. To learn more about queries, see https://graphql.org/learn/queries.
query {
  site {
    product1: product(entityId: 113) {
      ...ProductFields
    }
    product2: product(entityId: 115) {
      ...ProductFields
    }
  }
}
fragment ProductFields on Product {
  # fields on the Product object type 
}

Get product versus variant

The Product object is also used to retrieve variant information. For example, if you use the identifier variantEntityId or optionValueIds, you will retrieve information for the variant overlaid on the Product object (if the variant has a different values than the product). See Get a variant for more information.

Get a product with the products field

Query a list of products by using the products field and specifying product identifiers, for example, the product entityIDs:

Get a product with the products field

# This example retrieves one product.
# Specify multiple entityIds to retrieve multiple products.
query {
  site {
    products (entityIds: [111]) {
      edges {
        node {
          # fields on the Product object type
        }
      }
    }
  }
}

Query all products by not including an argument for products.

You can also query for featured products, related products, and more. See the GraphQL Storefront Playground for full schema documentation.

Get product identifiers

Query basic information for products. The following query retrieves both product identifiers and basic information for the specified product:

Request

Response

Example query: Get basic information for a product

1 query {
2   site {
3     product (entityId: 111) {
4       id
5       entityId
6       sku
7       path
8       name
9       description
10       addToCartUrl
11       upc
12       mpn
13       gtin  
14     }
15   }
16 }

Get product prices and dimensions

Query prices and dimensions for a product. The following query retrieves prices and dimensions for the specified product:

Request

Response

Example query: Get prices and dimensions for a product

1 # This query uses fragments. To learn more about fragments, see https://graphql.org/learn/queries/#fragments.
2 
3 query {
4   site {
5     product (entityId: 111) {
6       prices(currencyCode: USD) {
7         price {
8           ...PriceFields
9         }
10         salePrice {
11           ...PriceFields
12         }
13         basePrice {
14           ...PriceFields
15         }
16         retailPrice {
17           ...PriceFields
18         }
19       }
20       weight {
21         ...DimensionFields
22       }
23       height {
24         ...DimensionFields
25       }
26       width {
27         ...DimensionFields
28       }
29       depth {
30         ...DimensionFields
31       }
32     }
33   }
34 }
35 
36 # fields on the Money object type
37 fragment PriceFields on Money {               
38   currencyCode
39   value
40 }
41 
42 # fields on the Measurement object type
43 fragment DimensionFields on Measurement {     
44   value
45   unit
46 }

Get product options

Query the product options associated with a product. The response includes both variant options and modifier options. To retrieve only variant options, use a Get variant options query.

There are various types of product options available. Checkbox and multiple choice are some examples of the many option types available. Each type of product option has a schema type that implements the CatalogProductOption interface, meaning you can retrieve the common fields from CatalogProductOption for any type of product option. For more on interfaces, see the GraphQL Schema and Types- Interfaces (graphql.org) documentation.

CatalogProductOption interface

# Fields common among product option types
interface CatalogProductOption {
  entityId: Int!
  displayName: String!
  isRequired: Boolean!
  isVariantOption: Boolean!
}

The following example shows how to get the first three product options associated with a product. In the response, all product options include queried fields from the CatalogProductOption interface, and those that are checkbox or datefields include additional fields.

Request

Response

Example query: Get product options for a product

1 # This query uses interfaces. To learn more about interfaces, see https://graphql.org/learn/schema#interfaces.
2 
3 query {
4   site {
5     product (entityId: 115) {
6       productOptions (first: 3) {
7         edges {
8           node {
9             
10             # fields that all product options include
11             entityId                  
12             displayName
13             isRequired
14             isVariantOption
15             
16             # additional fields for checkbox options
17             ... on CheckboxOption {   
18               checkedByDefault
19               label
20             }
21             
22             # additional fields for datefield options
23             ... on DateFieldOption {  
24               earliest
25               latest
26               limitDateBy
27             }
28           }
29         }
30       }
31     }
32   }
33 }

When you get product options, you can retrieve the available values, or product option values, for product options that are multiple choice (Help Center). These values are made up of various types, swatch or radio buttons, for example. Each type of multiple choice value has a schema type that implements the CatalogProductOptionValue interface, meaning you can retrieve the common fields from CatalogProductOptionValue for any type of multiple choice value.

CatalogProductOptionValue interface

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

The following example shows a query that includes values for product options that are multiple choice. In the response, all product option values include queried fields from the CatalogProductOptionValue interface, and product option values that are swatch types include additional fields. The example query retrieves only the first product option and the first two values for that product option.

Request

Response

Example query: Get product options for a product

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

Get product images

Query the images for products. Note that the default image is a thumbnail for the product.

The following example retrieves the first two images and the default image for the specified product:

Request

Response

Example query: Get product images for a product

1 query {
2   site {
3     product (entityId: 113) {
4       images (first: 2) {
5         edges {
6           node {
7             url (width: 1)
8             urlOriginal
9             altText
10             isDefault
11           }
12         }
13       } 
14       defaultImage {
15         url (width: 1)
16         urlOriginal
17         altText
18         isDefault
19       }
20     }
21   }
22 }

You can query product images at different resolutions. The following query retrieves the first image for the specified product at various resolutions:

Request

Response

Example query: Get product images at different resolutions

1 # This query retrieves four images.
2 # This query uses aliases. To learn more about aliases, see https://graphql.org/learn/queries/#aliases.
3 
4 query {
5   site {
6     product(entityId: 113) {
7       images (first: 1) {
8         edges {
9           node {
10             url320wide: url(width: 320)
11             url640wide: url(width: 640)
12             url960wide: url(width: 960)
13             url1280wide: url(width: 1280)
14           }
15         }
16       }
17     }
18   }
19 }

Get product videos

The following example retrieves video titles and URLs associated with videos attached to a product.

Request

Response

Example query: Get product videos for a product

  query {
    site {
      products (entityIds: [112, 113]) {
        pageInfo {
            startCursor
            endCursor
        }
        edges {
              cursor
              node {
                  entityId
                  name
                  videos {
                    pageInfo {
                        startCursor
                        endCursor
                        hasNextPage
                        hasPreviousPage
                    }
                    edges {
                        cursor
                        node {
                            title
                            url
                        }
                    }
                  }
                }
              }
            }
          }
        }

Get product metafields

Query product metafields by specifying the product metafield’s namespace. 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 a product metafield endpoint.

Product versus variant metafields

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

The following query retrieves the first two product metafields for the specified product:

Request

Response

Example query: Get product metafields for a product

1 query {
2   site {
3     product (entityId: 113) {
4       metafields (first: 2 namespace: "Warehouse Locations") {
5         edges {
6           node {
7             id
8             entityId
9             key
10             value
11           }
12         }
13       } 
14     }
15   }
16 }

Get product custom fields

Query the custom fields for products. The following example retrieves the first two custom fields for the specified product:

Request

Response

Example query: Get custom fields for a product

1 query {
2   site {
3     product (entityId: 113) {
4       customFields (first: 2) {
5         edges {
6           node {
7             entityId
8             name
9             value
10           }
11         }
12       } 
13     }
14   }
15 }

Get product gift wrapping options

Query gift wrapping options that are available for a product. The following example retrieves the first two gift wrapping options for the specified product:

Request

Response

Example query: Get gift wrapping options for a product

1 query {
2   site {
3     product (entityId: 113) {
4       giftWrappingOptions (first: 2) {
5         edges {
6           node {
7             entityId
8             name
9             allowComments
10             previewImageUrl
11           }
12         }
13       } 
14     }
15   }
16 }

Get product condition

Query condition information for a product. Possible values are "NEW", "USED", "REFURBISHED", and null. If the option to show product condition is disabled, the expected return value is null. The following example retrieves the condition for the specified product:

Request

Response

Example query: Get condition for a product

1 query {
2   site {
3     product (entityId: 113) {
4       condition
5     }
6   }
7 }

Get product reviews

Query reviews for products. You retrieve only reviews that a merchant has approved. The following example retrieves the first review for the specified product:

Request

Response

Example query: Get reviews for a product

1 query {
2   site {
3     product (entityId: 113) {
4       reviews (first: 1) {
5         edges {
6           node {
7             entityId
8             author {
9               name
10             }
11             title
12             text
13             rating
14             createdAt {
15               utc
16             }
17           }
18         }
19       } 
20     }
21   }
22 }

Resources

GraphQL documentation

REST API reference

Catalog API - Products overview
Catalog API - Product options overview
Catalog API - Update a product metafield endpoint
Catalog API - Get product metafields endpoint
Catalog API - Get variant metafields endpoint

Support articles

Product options (Help Center)

GraphQL Storefront API

Guide to Working with Products

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

Price information in a store’s transacting currency
Product options associated with a product, both variant and modifier options
Product metafields that have storefront access

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

Get a Product

Get a product with the product field

You can query a product by using the product field and specifying a product identifier, for example, the product entityId.

Get a product with the product field

# This query retrieves one product.
query {
  site {
    product (entityId: 111) {
      # fields on the Product object type
    }
  }
}

Get a product with the product field

# This query retrieves two products.
# This query uses aliases and fragments. To learn more about queries, see https://graphql.org/learn/queries.
query {
  site {
    product1: product(entityId: 113) {
      ...ProductFields
    }
    product2: product(entityId: 115) {
      ...ProductFields
    }
  }
}
fragment ProductFields on Product {
  # fields on the Product object type 
}

Get product versus variant

Get a product with the products field

Query a list of products by using the products field and specifying product identifiers, for example, the product entityIDs:

Get a product with the products field

# This example retrieves one product.
# Specify multiple entityIds to retrieve multiple products.
query {
  site {
    products (entityIds: [111]) {
      edges {
        node {
          # fields on the Product object type
        }
      }
    }
  }
}

Query all products by not including an argument for products.

You can also query for featured products, related products, and more. See the GraphQL Storefront Playground for full schema documentation.

Get product identifiers

Query basic information for products. The following query retrieves both product identifiers and basic information for the specified product:

Request

Response

Example query: Get basic information for a product

1 query {
2   site {
3     product (entityId: 111) {
4       id
5       entityId
6       sku
7       path
8       name
9       description
10       addToCartUrl
11       upc
12       mpn
13       gtin  
14     }
15   }
16 }

Get product prices and dimensions

Query prices and dimensions for a product. The following query retrieves prices and dimensions for the specified product:

Request

Response

Example query: Get prices and dimensions for a product

1 # This query uses fragments. To learn more about fragments, see https://graphql.org/learn/queries/#fragments.
2 
3 query {
4   site {
5     product (entityId: 111) {
6       prices(currencyCode: USD) {
7         price {
8           ...PriceFields
9         }
10         salePrice {
11           ...PriceFields
12         }
13         basePrice {
14           ...PriceFields
15         }
16         retailPrice {
17           ...PriceFields
18         }
19       }
20       weight {
21         ...DimensionFields
22       }
23       height {
24         ...DimensionFields
25       }
26       width {
27         ...DimensionFields
28       }
29       depth {
30         ...DimensionFields
31       }
32     }
33   }
34 }
35 
36 # fields on the Money object type
37 fragment PriceFields on Money {               
38   currencyCode
39   value
40 }
41 
42 # fields on the Measurement object type
43 fragment DimensionFields on Measurement {     
44   value
45   unit
46 }

Get product options

Query the product options associated with a product. The response includes both variant options and modifier options. To retrieve only variant options, use a Get variant options query.

CatalogProductOption interface

# Fields common among product option types
interface CatalogProductOption {
  entityId: Int!
  displayName: String!
  isRequired: Boolean!
  isVariantOption: Boolean!
}

Request

Response

Example query: Get product options for a product

1 # This query uses interfaces. To learn more about interfaces, see https://graphql.org/learn/schema#interfaces.
2 
3 query {
4   site {
5     product (entityId: 115) {
6       productOptions (first: 3) {
7         edges {
8           node {
9             
10             # fields that all product options include
11             entityId                  
12             displayName
13             isRequired
14             isVariantOption
15             
16             # additional fields for checkbox options
17             ... on CheckboxOption {   
18               checkedByDefault
19               label
20             }
21             
22             # additional fields for datefield options
23             ... on DateFieldOption {  
24               earliest
25               latest
26               limitDateBy
27             }
28           }
29         }
30       }
31     }
32   }
33 }

CatalogProductOptionValue interface

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

Request

Response

Example query: Get product options for a product

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

Get product images

Query the images for products. Note that the default image is a thumbnail for the product.

The following example retrieves the first two images and the default image for the specified product:

Request

Response

Example query: Get product images for a product

1 query {
2   site {
3     product (entityId: 113) {
4       images (first: 2) {
5         edges {
6           node {
7             url (width: 1)
8             urlOriginal
9             altText
10             isDefault
11           }
12         }
13       } 
14       defaultImage {
15         url (width: 1)
16         urlOriginal
17         altText
18         isDefault
19       }
20     }
21   }
22 }

You can query product images at different resolutions. The following query retrieves the first image for the specified product at various resolutions:

Request

Response

Example query: Get product images at different resolutions

1 # This query retrieves four images.
2 # This query uses aliases. To learn more about aliases, see https://graphql.org/learn/queries/#aliases.
3 
4 query {
5   site {
6     product(entityId: 113) {
7       images (first: 1) {
8         edges {
9           node {
10             url320wide: url(width: 320)
11             url640wide: url(width: 640)
12             url960wide: url(width: 960)
13             url1280wide: url(width: 1280)
14           }
15         }
16       }
17     }
18   }
19 }

Get product videos

The following example retrieves video titles and URLs associated with videos attached to a product.

Request

Response

Example query: Get product videos for a product

  query {
    site {
      products (entityIds: [112, 113]) {
        pageInfo {
            startCursor
            endCursor
        }
        edges {
              cursor
              node {
                  entityId
                  name
                  videos {
                    pageInfo {
                        startCursor
                        endCursor
                        hasNextPage
                        hasPreviousPage
                    }
                    edges {
                        cursor
                        node {
                            title
                            url
                        }
                    }
                  }
                }
              }
            }
          }
        }

Get product metafields

Product versus variant metafields

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

The following query retrieves the first two product metafields for the specified product:

Request

Response

Example query: Get product metafields for a product

1 query {
2   site {
3     product (entityId: 113) {
4       metafields (first: 2 namespace: "Warehouse Locations") {
5         edges {
6           node {
7             id
8             entityId
9             key
10             value
11           }
12         }
13       } 
14     }
15   }
16 }

Get product custom fields

Query the custom fields for products. The following example retrieves the first two custom fields for the specified product:

Request

Response

Example query: Get custom fields for a product

1 query {
2   site {
3     product (entityId: 113) {
4       customFields (first: 2) {
5         edges {
6           node {
7             entityId
8             name
9             value
10           }
11         }
12       } 
13     }
14   }
15 }

Get product gift wrapping options

Query gift wrapping options that are available for a product. The following example retrieves the first two gift wrapping options for the specified product:

Request

Response

Example query: Get gift wrapping options for a product

1 query {
2   site {
3     product (entityId: 113) {
4       giftWrappingOptions (first: 2) {
5         edges {
6           node {
7             entityId
8             name
9             allowComments
10             previewImageUrl
11           }
12         }
13       } 
14     }
15   }
16 }

Get product condition

Request

Response

Example query: Get condition for a product

1 query {
2   site {
3     product (entityId: 113) {
4       condition
5     }
6   }
7 }

Get product reviews

Query reviews for products. You retrieve only reviews that a merchant has approved. The following example retrieves the first review for the specified product:

Request

Response

Example query: Get reviews for a product

1 query {
2   site {
3     product (entityId: 113) {
4       reviews (first: 1) {
5         edges {
6           node {
7             entityId
8             author {
9               name
10             }
11             title
12             text
13             rating
14             createdAt {
15               utc
16             }
17           }
18         }
19       } 
20     }
21   }
22 }

Resources

GraphQL documentation

REST API reference

Catalog API - Products overview
Catalog API - Product options overview
Catalog API - Update a product metafield endpoint
Catalog API - Get product metafields endpoint
Catalog API - Get variant metafields endpoint

Support articles

Product options (Help Center)

1	query {
2	site {
3	product (entityId: 111) {
4	id
5	entityId
6	sku
7	path
8	name
9	description
10	addToCartUrl
11	upc
12	mpn
13	gtin
14	}
15	}
16	}

1	# This query uses fragments. To learn more about fragments, see https://graphql.org/learn/queries/#fragments.
2
3	query {
4	site {
5	product (entityId: 111) {
6	prices(currencyCode: USD) {
7	price {
8	...PriceFields
9	}
10	salePrice {
11	...PriceFields
12	}
13	basePrice {
14	...PriceFields
15	}
16	retailPrice {
17	...PriceFields
18	}
19	}
20	weight {
21	...DimensionFields
22	}
23	height {
24	...DimensionFields
25	}
26	width {
27	...DimensionFields
28	}
29	depth {
30	...DimensionFields
31	}
32	}
33	}
34	}
35
36	# fields on the Money object type
37	fragment PriceFields on Money {
38	currencyCode
39	value
40	}
41
42	# fields on the Measurement object type
43	fragment DimensionFields on Measurement {
44	value
45	unit
46	}

1	# This query uses interfaces. To learn more about interfaces, see https://graphql.org/learn/schema#interfaces.
2
3	query {
4	site {
5	product (entityId: 115) {
6	productOptions (first: 3) {
7	edges {
8	node {
9
10	# fields that all product options include
11	entityId
12	displayName
13	isRequired
14	isVariantOption
15
16	# additional fields for checkbox options
17	... on CheckboxOption {
18	checkedByDefault
19	label
20	}
21
22	# additional fields for datefield options
23	... on DateFieldOption {
24	earliest
25	latest
26	limitDateBy
27	}
28	}
29	}
30	}
31	}
32	}
33	}

1	query {
2	site {
3	product (entityId: 113) {
4	images (first: 2) {
5	edges {
6	node {
7	url (width: 1)
8	urlOriginal
9	altText
10	isDefault
11	}
12	}
13	}
14	defaultImage {
15	url (width: 1)
16	urlOriginal
17	altText
18	isDefault
19	}
20	}
21	}
22	}

1	# This query retrieves four images.
2	# This query uses aliases. To learn more about aliases, see https://graphql.org/learn/queries/#aliases.
3
4	query {
5	site {
6	product(entityId: 113) {
7	images (first: 1) {
8	edges {
9	node {
10	url320wide: url(width: 320)
11	url640wide: url(width: 640)
12	url960wide: url(width: 960)
13	url1280wide: url(width: 1280)
14	}
15	}
16	}
17	}
18	}
19	}