bc-api-graphql · diff
git:20260309.786511c to git:20260914.08f85a3
1 added, 1 removed. Audit A to A.
---
name: bc-api-graphql
description: Use the BigCommerce GraphQL Storefront API — queries, mutations, authentication tokens, customer impersonation, cart operations, and schema exploration. Use when building storefront features that need client-side data fetching.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
---
# BigCommerce GraphQL Storefront API
## Before writing code
**Fetch live docs**:
- 1. Fetch `https://developer.bigcommerce.com/docs/storefront/graphql` for GraphQL overview
+ 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
## Key Queries
### Products
```graphql
query Products($first: Int, $after: String) {
site {
products(first: $first, after: $after) {
edges {
node {
entityId
name
path
prices {
price { value currencyCode }
salePrice { value currencyCode }
}
defaultImage {
url(width: 500)
altText
}
}
}
pageInfo { hasNextPage endCursor }
}
}
}
```
### Single Product
```graphql
query Product($productId: Int!) {
site {
product(entityId: $productId) {
entityId
name
description
prices { price { value currencyCode } }
images { edges { node { url(width: 800) altText } } }
productOptions { edges { node { entityId displayName } } }
variants { edges { node { entityId sku } } }
}
}
}
```
### Categories
```graphql
query Categories {
site {
categoryTree {
entityId
name
path
children { entityId name path }
}
}
}
```
### Cart
```graphql
query Cart {
site {
cart {
entityId
lineItems {
physicalItems {
entityId
name
quantity
listPrice { value currencyCode }
}
}
amount { value currencyCode }
}
}
}
```
### Customer (Requires Impersonation Token)
```graphql
query Customer {
customer {
entityId
firstName
lastName
email
addresses { edges { node { address1 city } } }
}
}
```
## Mutations
### Cart Operations
```graphql
mutation AddToCart($cartId: String!, $lineItems: [CartLineItemInput!]!) {
cart {
addCartLineItems(input: {
cartEntityId: $cartId
data: { lineItems: $lineItems }
}) {
cart { entityId }
}
}
}
```
### Create Cart
```graphql
mutation CreateCart($lineItems: [CartLineItemInput!]!) {
cart {
createCart(input: { lineItems: $lineItems }) {
cart { entityId }
}
}
}
```
### Customer Login
```graphql
mutation Login($email: String!, $password: String!) {
login(email: $email, password: $password) {
result
customer { entityId firstName }
}
}
```
## Pagination
Uses Relay-style cursor pagination:
- `first: N` — number of items
- `after: "cursor"` — cursor from `pageInfo.endCursor`
- `pageInfo { hasNextPage endCursor }` — pagination metadata
## Complexity Limits
GraphQL queries have complexity limits instead of request-count rate limits:
- Each field has a cost
- Nested connections multiply costs
- Use `first` arguments to limit results
- Avoid deeply nested queries
## Best Practices
- Request only the fields you need — avoid `SELECT *` mentality
- Use pagination (`first` + `after`) for large collections
- Cache responses where appropriate (products, categories change infrequently)
- Use customer impersonation tokens only when customer-specific data is needed
- Set appropriate token expiration (not too long)
- Restrict CORS origins for storefront tokens
- Use fragments for reusable field sets
- Handle errors in the `errors` array of the GraphQL response
Fetch the BigCommerce GraphQL Storefront API reference for the current schema, available queries/mutations, and authentication patterns before implementing.