GraphQL

GraphQL API Overview

BigCommerce offers several GraphQL APIs for different use cases:

  • Account API — Manage account-level resources such as users.
  • Admin API — Query and mutate store data server-side.
  • Storefront API — Query products, customers, and carts from the storefront.
  • B2B API — Manage B2B Edition resources such as companies, quotes, and shopping lists.

For authentication details specific to GraphQL, see GraphQL Storefront Authentication.

Some Storefront API operations depend on customer context. Sending a request as a signed-in customer can change what a query returns (such as customer-specific pricing) and is required for some operations to work at all. registerCompany, for example, must be called as a signed-in customer. If an operation returns empty data or an authentication error when you expected results, confirm you’re sending a customer context. See Customer context in the GraphQL Storefront API.

GraphQL HTTP status codes

All GraphQL errors return a 401 HTTP status code.

CodeTextPurpose
401UnauthorizedThis response is sent when your client failed to provide credentials or its credentials were invalid.
”GraphQL credentials were missing. No token was sent.”No token sent. The token was missing.
”GraphQL invalid credentials. String is not a JWT”Invalid JWT sent. The token was not a well-formed JWT.
”GraphQL invalid credentials. JWT signature is invalid”One of the JWT claims failed. The token was not generated by BigCommerce.
”GraphQL invalid credentials. JWT is expired”Token has expired.
”GraphQL invalid credentials. JWT channel id doesn’t match channel id of the URL”Channel ID mismatch. The channel ID in the token does not match channel ID of the site URL.
”Unknown JWT token”JWT was revoked.
”GraphQL invalid credentials. JWT has no valid Json”Invalid JWT sent. Token has no valid JSON.
”GraphQL invalid credentials. JWT has Json of an unknown format”Invalid JWT sent. Token has no valid JSON.
”GraphQL invalid credentials. JWT store id doesn’t match store id of the URL”Store ID in the token does not match store ID of the site URL.

GraphQL-specific response headers

HeaderPossible ValuesDescriptionExample
x-bc-graphql-complexityintegerIndicates the computed complexity score of the executed GraphQL query. If this exceeds 10000, an error is returned.5241
x-bc-graphql-query-hashstringA ‘sha256’ hash of the query body, not including variables. This allows identification of specific queries among those with non-unique names.bd2e22a00004abd3ec9437a6f895
x-bc-graphql-variables-hashstringA sha256 hash of the variables included in a query.44136fa355b3678a1146ad16f7e8
x-bc-graphql-operation-typeOne of query, mutation, or subscriptionThe operation type of the request. Currently, subscription is not supported.query
x-bc-graphql-operation-namestringThe operation name within a query. Used with queries with multiple operations. This will return an empty string for anonymous requests.HomePageQuery