Home > BigCommerce > Docs > Introduction to GraphQL & BigCommerce

Introduction to GraphQL & BigCommerce

Last updated: September 01, 2024
Written and researched by experts at AvadaLearn more about our methodology

By Sam Nguyen

CEO Avada Commerce

Do you know about GraphQL?

Perhaps some people will say “YES,” but the majority will have the NO answer. Regarded as an alternative to REST API, GraphQL possesses plenty of features to help developers make it easier to manage and develop their eCommerce store. This is also the reason why BigCommerce, one of the most popular platforms for online stores, develops and introduces this feature to their merchants.

So, what exactly is GraphQL? What can it bring to users? How is GraphQL used in BigCommerce? All will be answered in this post! Also, you will see an example of GraphQL on this platform.

About GraphQL

GraphQL logo

GraphQL is a type of programming language which is known as an open-source data queries and manipulation language for APIs. Initially developed by Facebook in 2012, GraphQL’s owner then was changed to Lux Foundation in 2018. After nearly 10 years of development, this programming language has become a strong competitor of REST and other web service architectures.

With GraphQL, clients will be able to request exactly what they need via HTTP protocol. IT enables users to set a certain structure of data needed, and then the system will return the data with the same structure as had been set. This helps clients avoid the case of too much data returned and work with the data more efficiently.

More than that, GraphQL can be used in plenty of languages, such as JavaScript, Haskell, Perl, Python Development Company, Java, C++, and more.

How to access & use the BigCommerce GraphQL Playground

Step 1: Access the playground

First, log in to your store to use the GraphQL Storefront API Playground and check out its documentation. Then, go to Settings, API, and Storefront API Playground.

access the playground

Once you click on that, the GraphQL Storefront API Playground will pop up, ready for you to explore.

bigcommerce graphql

Note: If you can’t see the link for the Storefront API Playground, your store isn’t using a Stencil theme. To fix this, apply a Stencil theme, and you’ll be good to go, ready to delve into the GraphQL Storefront API.

Step 2: Use the playground

The GraphQL Playground is a handy tool for interacting with GraphQL APIs. To utilize its features, you start by entering your queries on the left side of the interface. These queries specify the data you want to retrieve from the API.

Once you’ve crafted your query, click the Play button near the top-left corner. This action sends your query to the API, and the results are displayed on the right side of the Playground. This real-time feedback loop lets you quickly test your queries and see the corresponding data.

Here’s a basic example of a query you might run in the GraphQL Playground: In this query, we’re asking for a list of products, and each product, we’re requesting its ID, name, and price.

query MyQuery {
  site {
    settings {
      storeName
    }
    products {
      edges {
        node {
          name
          sku
          prices {
            retailPrice {
              value
              currencyCode
            }
            price {
              value
              currencyCode
            }
          }
        }
      }
    }
  }
}

bigcommerce graphql

If you’re not sure what queries are available or how to structure them, you can explore the GraphQL schema using the Docs and Explorer tabs on the right side of the Playground. The Docs tab provides detailed documentation for the API’s available types, fields, and operations.

bigcommerce graphql

Additionally, BigCommerce provides a GraphQL Explorer tool, allowing you to explore your data’s graph visually. This tool can be particularly useful for understanding the relationships between different data types and discovering available query options.

Step 3: Authentication process

Authentication with the GraphQL Storefront API involves JWT (JSON Web Token) bearer tokens sent via the HTTP Authorization header. This ensures that only authorized requests are accepted by the API. Token Creation To access the GraphQL Storefront API, you must generate a token through the “Create a storefront token” REST endpoint. This endpoint requires a token creation scope, which you can add to your store-level or app-level API account. These tokens act as keys to authenticate your requests to the API. By specifying the necessary parameters, such as the expiration time and allowed CORS origins, you can tailor the token to your specific authentication requirements.

→ Example request: Create a GraphQL Storefront API token

POST https://api.bigcommerce.com/stores//v3/storefront/api-token
x-auth-token: 
accept: application/json
content-type: application/json 
{
  "channel_id": 1,            // An integer representing the channel ID on the store where the token will be used. It must be a valid channel ID.
  "expires_at": 86400000,   // The expiration time of the token, specified as an integer Unix timestamp (in seconds).
  "allowed_cors_origins": [   // An array of origins specifying the CORS (Cross-Origin Resource Sharing) origins that are allowed to use the token. Up to two origins per token are allowed. In this example, only https://mydomain.com is allowed.
    "https://mydomain.com"
  ]
}

Auto-Generated Token Utilization in Stencil Themes

In Stencil themes, integrating tokens is made easier through auto-generation. These tokens are automatically passed to client code during theme rendering using Handlebars properties. You don’t have to manually generate tokens through the Admin API before utilizing the Storefront API in your Stencil theme. The auto-generated tokens typically have an expiry period of 24-48 hours and periodically rotate before expiration, ensuring continued access to the API.

Customer Impersonation Token Generation

Customer Impersonation Tokens are crucial in server-to-server and headless interactions with the GraphQL Storefront API. These tokens allow you to authenticate requests on behalf of any customer, enabling you to access store information from their perspective. However, handling these tokens carefully is important, as they are sensitive and should never be publicly exposed. They should be treated like other application secrets to maintain security. → Example request: Create a customer impersonation token

POST https://api.bigcommerce.com/stores//v3/storefront/api-token-customer-impersonation
x-auth-token: 
accept: application/json
content-type: application/json
{
  "channel_id": 1, // An integer representing the channel ID on the store where the token will be used. It must be a valid channel ID.
  "expires_at": 86400000 // The expiration time of the token, specified as an integer Unix timestamp (in seconds).
}

Customer Login Process

The Customer Login mutation authenticates customer accounts. This mutation enables customers to sign in to their accounts using their email address and password. Upon successful authentication, a session cookie is set in the browser, authenticating subsequent requests to the storefront. Customer login provides a seamless and secure authentication mechanism for shoppers accessing the storefront, enhancing their user experience.

Step 4: Apply the GraphQL API to the BigCommerce storefront

To apply the GraphQL API to your BigCommerce storefront, you have a couple of options: you can make API calls directly from within a Stencil theme, or you can use scripts in the store’s Script Manager. Here’s an example of how you can make a GraphQL request using a Stencil auto-generated token and JavaScript’s Fetch API:

<script>
fetch('/graphql', {
  method: 'POST',
  credentials: 'same-origin',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' // use auto-generated token
  },
  body: JSON.stringify({
    query: `query MyFirstQuery {
      site {
        settings {
          storeName
        }
        products {
          edges {
            node {
              name
              sku
              defaultImage {
                url(width: 1280)
              }
            }
          }
        }
      }
    }`
  })
})
.then(res => res.json())
.then(data => console.log(data)) // will log JSON result to browser console
.catch(error => console.error(error));
</script>

This script sends a GraphQL query to the specified endpoint (/graphql). It includes the necessary headers, such as the authorization token obtained from settings.storefront_api.token. The query fetches information about the site settings, including the store name and product details, such as their names, SKUs, and default image URLs. If you’re dealing with pagination for nodes that return multiple items, you can limit the number of items retrieved. You can find more information about pagination in the BigCommerce documentation. Additionally, consider using client libraries like Apollo, which offer features to simplify GraphQL implementations. These libraries provide declarative data fetching, state management, and caching, which can lead to more consistent UI components. Check out examples of adding Apollo Client to specific BigCommerce themes on GitHub if interested.

Benefits of GraphQL

Benefits of GraphQL

Easy to expand query

In GraphQL, it is pretty simple to create a request. For example, you can make a request to retrieve a heroine like this:

{

heroine {

name

}

}

But, what can you do if your boss then requires her family members? Create one more call to the endpoint of her family members like heroines/family as in RESTful API?

Actually, the key for it is much simpler, GraphQL empowers users to add more data required in their query. Hence, instead of getting another all, the query can be lengthened like:

{

heroine {

name

family members {

name

}

}

}

Strict in values

In fact, GraphQL is considered a strongly-typed language which means it will be harder for the data to be accepted. In addition, its explanation about the error is also understandable so that users can quickly find out the errors and fix them.

Access data in only one endpoint

There is only one endpoint for all requests in GraphQL. When you make changes to your front end, the back end will no longer need to be re-architectured every time, which helps users provide their customers the latest news in a rapid manner. It allows them to update the market trends and satisfy customer feedback without wrangling and tweaking the models and controllers.

About BigCommerce GraphQL

BigCommerce GraphQL

GraphQL in BigCommerce enables users to request storefront data from the Stencil theme or remote sites. Thus, you now can access data (that are unavailable via the Stencil objects) from the frontend Javascript instead of opening the backend from the template logic as before. As a result, you can implement multiple tasks, such as accessing product options, querying product images, getting customers’ information, seeking brands, constructing front-end apps, etc.

More than that, GraphQL can streamline the workflows and improve store’s performance by exploiting data from an API call. Users will be provided with all the benefits from the BigCommerce backend without compromising on the technology that can be used on the frontend. Thus, they will have more time and money to enhance the customer experience in their store.

Besides, you should keep in mind that BigCommerce GraphQL storefront API is still being developed so that only when reaching the necessary features to offer a full shopping experience do we remove its’ early access status. Also, you can see all the new functionalities in the Developer Changelog. Additionally, the GraphQl API is recently not supported in Blueprint themes.

GraphQL BigCommerce samples

To get the first three levels of category tree, users can use this:

query CategoryTree3LevelsDeep {

` site {`

` categoryTree {`

` …CategoryFields`

` children {`

` …CategoryFields`

` children {`

` …CategoryFields`

` }`

` }`

` }`

` }`

}

` `

fragment CategoryFields on CategoryTreeItem {

` name`

` path`

` entityId`

}

The response will be:

{

` “data”: {`

` “site”: {`

` “categoryTree”: [`

` {`

` “name”: “Kitchen”,`

` “path”: “/kitchen/”,`

` “entityId”: 27,`

` “children”: []`

` },`

` {`

` “name”: “Publications”,`

` “path”: “/publications/”,`

` “entityId”: 26,`

` “children”: []`

` },`

` {`

` “name”: “Shop All”,`

` “path”: “/shop-all/”,`

` “entityId”: 23,`

` “children”: []`

` },`

` {`

` “name”: “Utility”,`

` “path”: “/utility/”,`

` “entityId”: 25,`

` “children”: []`

` },`

` {`

` “name”: “Garden”,`

` “path”: “/garden/”,`

` “entityId”: 19,`

` “children”: [`

` {`

` “name”: “Bath”,`

` “path”: “/garden/bath/”,`

` “entityId”: 24,`

` “children”: []`

` }`

` ]`

` }`

` ]`

` }`

` }`

}

Final thoughts

In conclusion, it can’t be denied that GraphQL is a useful way to help people get the necessary data in a short time. In fact, GraphQL is still a feature-incomplete in BigCommerce, but it can help you a lot to develop your business. BigCommerce users will save lots of time for accessing information and use this amount of time for other essential things.

Yes, you can hide the display of specific fields in GraphQL by toggling off the relevant setting in the control panel. For example, turning off the "show_product_price" field will result in the "prices" field returning null in the GraphQL response.

You'll need to use the channel's permanent URL to run requests in the context of a different channel. This URL follows the format: https://store-STOREHASH-CHANNELID.mybigcommerce.com/graphql. For example, if your store hash is "abc789" and your channel ID is "123", the channel's permanent URL would be: https://store-abc789-123.mybigcommerce.com/graphql. Before a channel's permanent URL can respond to requests, you must create a site for that channel. When making a GraphQL Storefront API token, ensure that the channel ID of the desired channel is included, or the server will reject your requests.

You can utilize a standard GraphQL Storefront API token for this purpose. Ensure that when creating your token, you specify the origin from which your requests will be made. This step is crucial for allowing Cross-Origin Resource Sharing (CORS) and ensuring that requests from your specified origin are permitted. Additionally, you can use an anonymous fetch or XHR mode, which avoids sending cookies along with the request. This setup enables you to securely access anonymous information without requiring user authentication.

Sam Nguyen is the CEO and founder of Avada Commerce, an e-commerce solution provider headquartered in Singapore. He is an expert on the Shopify e-commerce platform for online stores and retail point-of-sale systems. Sam loves talking about e-commerce and he aims to help over a million online businesses grow and thrive.

Stay in the know

Get special offers on the latest news from AVADA.