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:
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:
POST https://{{storeDomain}}/graphql
Authorization: Bearer {{storefrontOrCustomerImpersonationToken}}
X-BC-Customer-ID: 123 # optional once a customer is signed in
Content-Type: application/jsonGet 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
}
}
}
}Get first three levels of category tree
query CategoryTree3LevelsDeep {
site {
categoryTree {
...CategoryFields
children {
...CategoryFields
children {
...CategoryFields
}
}
}
}
}
fragment CategoryFields on CategoryTreeItem {
name
path
entityId
}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
}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
}
}
}
}
}
}Get popular brands
query {
site {
popularBrands {
edges {
node {
entityId
count
name
path
}
}
}
}
}Get a favicon
query Favicon {
site {
settings {
faviconUrl
}
}
}Get analytics ID
Analytics IDs are available only after configuring the analytics service provider for your store.
query {
site {
settings {
webAnalytics {
ga4 {
tagId
}
metaPixel {
pixelId
}
segment {
writeKey
}
}
}
}
}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.
{
geography {
countries {
entityId
code
name
statesOrProvinces {
entityId
name
abbreviation
}
}
}
}Get wishlist information
Wishlists are accessible through GraphQL and offer access to all standard wishlist management functions. In addition to retrieving information through the queries customers.wishlists and site.publicWishlist outlined below, the mutations createWishlist, addWishlistItems, deleteWishlistItems, updateWishlist, and deleteWishlists are provided for managing customer wishlists.
Public wishlists are read-only within GraphQL.
The items field in both customer and public wishlist queries greatly increases query complexity. This means that the cost for deeply nested or large queries involving wishlist items grows rapidly. As a result, complex queries may hit rate or complexity limits sooner than expected. For platform stability, plan queries with this in mind and retrieve only the data you need.
Customer wishlists
Customer wishlists are queried based on the current customer session, using the token generated during the authentication process to identify the customer for the query's response data.
query {
customer {
wishlists {
edges {
node {
id
name
items {
edges {
node {
entityId
productName
}
}
}
}
}
}
}
}Public wishlists
You can also access public wishlists using a token. The items field in public wishlists is affected by the same complexity considerations:
query {
site {
publicWishlist(token: "TOKEN_HERE") {
id
name
items {
edges {
node {
entityId
productName
}
}
}
}
}
}