GraphQL Storefront API Example Queries

Below are example GraphQL queries for use with the BigCommerce GraphQL Storefront API. The purpose of these examples is to assist developers in getting familiar with the API. For a general overview of its usage and capabilities, see GraphQL Storefront API overview.

Configuring the request

To get started, you need a BigCommerce store and a Storefront API token. For more information, see the Authenticating requests to the GraphQL Storefront API or the General authentication article.

For more information on formatting the request payload, see the query example section of the GraphQL Storefront API overview.

To use this API from a coupled storefront, use the following HTTP configuration:

Example query: Same-origin GraphQL Storefront HTTP configuration

  fetch('/graphql', {
    method: 'POST',
    credentials: 'same-origin',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ' + {{storefrontToken}}
    },
    body: JSON.stringify({
      query: gqlQueryString
    })
  })
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.error(error));

To use this API server-to-server, use the following HTTP configuration:

Server-to-server GraphQL Storefront HTTP configuration

  POST https://{{storeDomain}}/graphql
  Authorization: Bearer {{storefrontOrCustomerImpersonationToken}}
  X-BC-Customer-ID: 123 # optional once a customer is signed in
  Content-Type: application/json

Get a customer's details

Example query: Get a customer's details

query CustomerAttributes {
  customer {
    firstName
    lastName
    email
    entityId
    customerGroupId
    attributeCount
    attributes {
      shirtSize: attribute(entityId:123) {
        entityId
        value
      }
      favoriteColor: attribute(entityId:456) {
        entityId
        value
      }
    }
  }
}

Try it in GraphQL Playground

Get first three levels of category tree

Example query: Get first three levels of category tree

query CategoryTree3LevelsDeep {
  site {
    categoryTree {
      ...CategoryFields
      children {
        ...CategoryFields
        children {
          ...CategoryFields
        }
      }
    }
  }
}
 
fragment CategoryFields on CategoryTreeItem {
  name
  path
  entityId
}

Try it in GraphQL Playground

Get category and products within by URL

Example query: Get category and products within by URL

query CategoryByUrl {
  site {
    route(path: "/shop-all/") {
      node {
        id
        ... on Category {
          name
          entityId
          description
          products {
            edges {
              node {
                name
                defaultImage {
                  url(width: 1200)
                }
                brand {
                  name
                  defaultImage {
                    url(width: 200)
                  }
                }
                prices {
                  price {
                    ...PriceFields
                  }
                  priceRange {
                    min {
                      ...PriceFields
                    }
                    max {
                      ...PriceFields
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
 
fragment PriceFields on Money {
  value
  currencyCode
}

Try it in GraphQL Playground

Look up an object by URL

Example query: Look up an object by URL

query LookUpUrl {
  site {
    route(path: "/shop-all/") {
      node {
        __typename
        id
        ... on Category {
          name
          description
        }
        ... on Brand {
          name
          defaultImage {
            url(width: 200)
          }
        }
        ... on Product {
          name
          description
          images {
            edges {
              node {
                url(width: 500, height: 500)
              }
            }
          }
          brand {
            name
          }
        }
      }
    }
  }
}

Try it in GraphQL Playground

Get popular brands

Example query: Get popular brands

query {
  site {
    popularBrands {
      edges {
        node {
          entityId
          count
          name
          path
        }
      }
    }
  }
}

Try it in GraphQL Playground

Get a favicon

Example query: Get the storefront's favicon

query Favicon {
  site {
    settings {
      faviconUrl
    }
  }
}

Try it in GraphQL Playground

Get analytics ID

Analytics IDs are available only after configuring the analytics service provider for your store.

Example query: Get analytics ID

 query {
    site {
      settings {
        webAnalytics {
          ga4 {
            tagId
        }
          metaPixel {
            pixelId
        }
          segment {
            writeKey
        }
      }
    }
  }
}

Try it in GraphQL Playground

Get a list of countries

The geography node provides a list of all supported shipping countries and their corresponding states or provinces. By default, the full list is returned unless you apply a filter. To narrow down the list, you can use the Settings > Shipping > Checkout shipping options filter in the control panel. This filter limits the results to only those countries included in your active shipping zones.

The geography node currently supports two filters, both available on the level of countries: code and name. These require exact matches to the country's two-letter country code and full name, respectively.

Example query: Get list of countries via geography

 {
  geography {
    countries {
      entityId
      code
      name
      statesOrProvinces {
        entityId
        name
        abbreviation
      }
    }
  }
}

Try it in GraphQL Playground

Did you find what you were looking for?

Routes and content Products