CoursesGraphQL Storefront APIModule 2: Authentication

Querying Within a BigCommerce Storefront

Plan: Developer Foundations

 Lesson 7 of 28 · 15 min

YAML Front Matter

YAML Front Matter is used at the top of Stencil templates to configure certain details about the data loaded during the page render and made available to the Handlebars template context. A gql attribute in this front matter can be used to build a custom query to the GraphQL Storefront API.

A query declared in this way will be run before the page response is returned, and the GraphQL response data will be available for direct use within the Stencil template. Because of the context of these requests, they do not require any manual authentication token management.

The following is an example of front matter making a query for a product’s metafields, which would be possible in the product.html template where the $productId variable is automatically made available to GraphQL queries.

gql: "query productById($productId: Int!) {
 site {
   product(entityId: $productId) {
     variants(first: 25) {
       edges {
         node {
           metafields(namespace: "Example Category") {
             edges {
               node {
                 key
                 value
               }
             }
           }
         }
       }
     }
   }
 }
}"

Any data in the GraphQL response could then be used in Handlebars:

{{#if gql.data.site.product}}
{{#each gql.data.site.product.metafields.edges}}
  {{#with node}}
    <label>{{key}}:</label> {{value}}
  {{/with}}
{{/each}}
{{/if}}

Different Stencil templates make different GraphQL variables available to front matter, as listed in the BigCommerce documentation.

Client-Side Use

GraphQL Storefront API calls can be made directly in client-side JS from within a Stencil theme or from a script in the Script Manager. This can be accessed in the control panel in Storefront > Script Manager for single storefront or Channel Manager > Edit Settings for a Channel > Script Manager for multi-storefront.

Stencil makes a standard storefront token available automatically. You’re not required to generate a token of your own for this context.

Deprecation notice for normal/storefront tokens: Normal/storefront tokens created after June 30, 2026 will no longer support server-to-server (S2S) requests. Normal/storefront tokens created on or before June 30, 2026 will be able to make S2S calls until March 31, 2027. For server-to-server integrations, use private tokens instead. Browser-based usage (such as the example below) is not affected.

Here’s an an example request using the {{settings.storefront_api.token}} handlebars object and fetch():

<script>
fetch('/graphql', {
  method: 'POST',
  credentials: 'same-origin',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{ settings.storefront_api.token }}' // 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>

The above code must be used in a place where the {{settings.storefront_api.token}} handlebars variable can be accessed in order to get credentials for the API request. For example, .html files in Stencil themes and Script Manager.

The fetch request’s credentials property must be set to same-origin.

In addition to using fetch(), there are other ways to query the API:

  • Using Apollo Client - Apollo is a popular GraphQL client that is easy to use in BigCommerce themes. For a quick example of adding Apollo Client to Cornerstone, checkout this Cornerstone commit on GitHub.
  • Using any GraphQL Client - GraphQL is a standard with client libraries in many languages, so feel free to explore your options.

Resources