GraphQL Storefront API

  • Host: {$$.env.store_domain}/graphql
  • Protocols: https
  • Accepts: application/json
  • Responds With: application/json

Use GraphQL to query data for headless storefronts and BigCommerce Stencil powered storefronts.

GraphQL Playground

To access the GraphQL Storefront API Playground and documentation, log in to your store and navigate to Advanced Settings > Storefront API Playground.

If you don’t yet have a store and would like to experiment making queries against a staging site, visit the GraphQL Playground directly on the Dev Center.

GraphQL Explorer

To explore Storefront nodes in an interactive graph, checkout out the GraphQL Explorer.

Authentication

Tokens via API

Create JWT tokens for authenticating cross-origin requests by making a POST request to /v3/storefront/api-token.

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/endpoint
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

{
  "channel_id": 1,
  "expires_at": 1602288000,
  "allowed_cors_origins": [
    "https://example.com"
  ]
}

Open in Request Runner

Tokens via handlebars

Client code on BigCommerce Stencil powered storefronts can be passed a token at render time with the {{settings.storefront_api.token}} Handlebars object.

fetch('/graphql', {
	method: 'POST',
	headers: {
	 'Content-Type': 'application/json',
	 'Authorization': 'Bearer {{settings.storefront_api.token}}'
	},
	body: JSON.stringify({ query: '{ site { ... } }' }),
});

Customer impersonation tokens

It’s also possible to generate tokens for use in server-to-server interactions with a trusted consumer. To create a customer impersonation token, send a POST request to /v3/storefront/api-token-customer-impersonation.

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/storefront/api-token-customer-impersonation
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json

{
  "channel_id": 1,
  "expires_at": 1602288000
}

Open in Request Runner

Response:

{
  "data":
  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
  }
  "meta": {}
}

Logging in a customer

If you’re using the Storefront API from a browser (for example, on top of your Stencil storefront) you can use the Customer Login mutation to log in a customer account with an email address and password (for server-side integrations, consider a customer impersonation token instead). This will set a session cookie in the browser which will authenticate the customer account on future requests:

mutation Login($email: String!, $pass: String!) {
  login(email: $email, password: $pass) {
    result
  }
}

As a best practice, you should inject the password using GraphQL query variables. This prevents the password from being exposed in the query itself. In the GraphQL Playground, you can set the variables for the request:

Learn more about GraphQL Storefront API Authentication.

Additional information