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 (opens in a new tab).
International Enhancements for Multi-Storefront (opens in a new tab) 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 (opens in a new tab). 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.
# This query retrieves one product.
query {
site {
product (entityId: 111) {
# fields on the Product object type
}
}
}# 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:
# 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 (opens in a new tab) 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:
query {
site {
product (entityId: 111) {
id
entityId
sku
path
name
description
addToCartUrl
upc
mpn
gtin
}
}
}Get product prices and dimensions
Query prices and dimensions for a product. The following query retrieves prices and dimensions for the specified product:
# This query uses fragments. To learn more about fragments, see https://graphql.org/learn/queries/#fragments.
query {
site {
product (entityId: 111) {
prices(currencyCode: USD) {
price {
...PriceFields
}
salePrice {
...PriceFields
}
basePrice {
...PriceFields
}
retailPrice {
...PriceFields
}
}
weight {
...DimensionFields
}
height {
...DimensionFields
}
width {
...DimensionFields
}
depth {
...DimensionFields
}
}
}
}
# fields on the Money object type
fragment PriceFields on Money {
currencyCode
value
}
# fields on the Measurement object type
fragment DimensionFields on Measurement {
value
unit
}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) (opens in a new tab) documentation.
# 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.
# This query uses interfaces. To learn more about interfaces, see https://graphql.org/learn/schema#interfaces.
query {
site {
product (entityId: 115) {
productOptions (first: 3) {
edges {
node {
# fields that all product options include
entityId
displayName
isRequired
isVariantOption
# additional fields for checkbox options
... on CheckboxOption {
checkedByDefault
label
}
# additional fields for datefield options
... on DateFieldOption {
earliest
latest
limitDateBy
}
}
}
}
}
}
}When you get product options, you can retrieve the available values, or product option values, for product options that are multiple choice (Help Center) (opens in a new tab). 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.
# 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.
# This query uses interfaces. To learn more about interfaces, see https://graphql.org/learn/schema/#interfaces.
query {
site {
product (entityId: 113) {
productOptions (first: 1) {
edges {
node {
# fields that all product options include
entityId
displayName
isRequired
isVariantOption
# additional fields for multiple choice options
... on MultipleChoiceOption {
displayStyle
values (first: 2) {
edges {
node {
entityId
label
isDefault
# additional fields for swatch options
... on SwatchOptionValue {
hexColors
imageUrl (width: 2)
}
}
}
}
}
}
}
}
}
}
}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:
query {
site {
product (entityId: 113) {
images (first: 2) {
edges {
node {
url (width: 1)
urlOriginal
altText
isDefault
}
}
}
defaultImage {
url (width: 1)
urlOriginal
altText
isDefault
}
}
}
}You can query product images at different resolutions. The following query retrieves the first image for the specified product at various resolutions:
# This query retrieves four images.
# This query uses aliases. To learn more about aliases, see https://graphql.org/learn/queries/#aliases.
query {
site {
product(entityId: 113) {
images (first: 1) {
edges {
node {
url320wide: url(width: 320)
url640wide: url(width: 640)
url960wide: url(width: 960)
url1280wide: url(width: 1280)
}
}
}
}
}
}Get product videos
The following example retrieves video titles and URLs associated with videos attached to 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:
query {
site {
product (entityId: 113) {
metafields (first: 2 namespace: "Warehouse Locations") {
edges {
node {
id
entityId
key
value
}
}
}
}
}
}Get product custom fields
Query the custom fields for products. The following example retrieves the first two custom fields for the specified product:
query {
site {
product (entityId: 113) {
customFields (first: 2) {
edges {
node {
entityId
name
value
}
}
}
}
}
}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:
query {
site {
product (entityId: 113) {
giftWrappingOptions (first: 2) {
edges {
node {
entityId
name
allowComments
previewImageUrl
}
}
}
}
}
}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:
query {
site {
product (entityId: 113) {
reviews (first: 1) {
edges {
node {
entityId
author {
name
}
title
text
rating
createdAt {
utc
}
}
}
}
}
}
}Resources
GraphQL documentation
- GraphQL Storefront API overview
- Guide to working with product variants
- 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 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