DocsStorefrontGuidesGraphQL StorefrontProducts & Catalog

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:

Example query: Get basic information for a 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:

Example query: Get prices and dimensions for a 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) 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.

Example query: Get product options for a product
# 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). 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.

Example query: Get product options for a product
# 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:

Example query: Get product images for a 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:

Example query: Get product images at different 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.

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:

Example query: Get product metafields for a 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:

Example query: Get custom fields for a 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:

Example query: Get gift wrapping options for a product
query {
  site {
    product (entityId: 113) {
      giftWrappingOptions (first: 2) {
        edges {
          node {
            entityId
            name
            allowComments
            previewImageUrl
          }
        }
      } 
    }
  }
}

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:

Example query: Get condition for a product
query {
  site {
    product (entityId: 113) {
      condition
    }
  }
}

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:

Example query: Get reviews for a product
query {
  site {
    product (entityId: 113) {
      reviews (first: 1) {
        edges {
          node {
            entityId
            author {
              name
            }
            title
            text
            rating
            createdAt {
              utc
            }
          }
        }
      } 
    }
  }
}

Resources

GraphQL documentation

REST API reference

Support articles