bc-api-graphql

BigCommerce GraphQL Storefront API

Before writing code

Fetch live docs:

1. Fetch https://docs.bigcommerce.com/developer/docs/storefront/guides/graphql-storefront-api/overview for GraphQL overview
2. Web-search site:developer.bigcommerce.com graphql storefront api reference for schema reference
3. Web-search bigcommerce graphql storefront token for token creation

Architecture

What It Is

A client-side GraphQL API designed for storefront applications:

• Endpoint: https://{store_domain}/graphql
• Designed for browser/frontend usage (not server-to-server)
• Fetch exactly the data you need in a single request
• Supports: products, categories, cart, checkout, customer, site settings, content

When to Use

• Stencil themes — client-side AJAX calls for dynamic content
• Headless storefronts — Catalyst/Next.js primary data source
• Single-page applications — React, Vue, Angular storefronts
• Progressive enhancement — add dynamic features to server-rendered pages

GraphQL vs REST

Feature	GraphQL Storefront	REST API
Audience	Frontend/browser	Backend/server
Auth	Storefront token	API account token
Data shape	Client-defined	Server-defined
Rate limits	Complexity-based	Request count
Mutations	Cart, checkout, login	Full CRUD

Authentication

Storefront API Token

Create via REST API:

POST /v3/storefront/api-token
{
  "channel_id": 1,
  "expires_at": 1893456000,
  "allowed_cors_origins": ["https://my-storefront.com"]
}

Returns a token to use as Authorization: Bearer {token} header.

Customer Impersonation Token

For accessing customer-specific data (addresses, orders, wishlists):

POST /v3/storefront/api-token-customer-impersonation
{
  "channel_id": 1,
  "expires_at": 1893456000
}

Combine with X-Bc-Customer-Id header for customer-specific queries.

Stencil Theme Context

In Stencil themes, the GraphQL token is available automatically:

• Use {{inject 'graphQLToken' settings.storefront_api.token}} in templates
• Or fetch from /api/storefront/graphql-token endpoint