BigCommerce Headless Commerce
Before writing code
Fetch live docs:
- Fetch
https://www.catalyst.dev/ for Catalyst documentation
- Web-search
site:developer.bigcommerce.com headless for headless guide
- Web-search
site:github.com bigcommerce catalyst for Catalyst source and examples
Headless Architecture
What Headless Means for BigCommerce
Decouple the frontend from BigCommerce:
- BigCommerce serves as the commerce backend — catalog, orders, customers, payments
- Your custom frontend handles presentation — React, Next.js, Vue, etc.
- Communication via APIs — GraphQL Storefront API and REST API
- Checkout via Embedded Checkout or Custom Checkout (Checkout API + Payments API)
Why Headless
- Full frontend control (design, UX, performance)
- Use modern frameworks (Next.js, Remix, Astro)
- Composable architecture — mix BigCommerce with CMS, search, etc.
- Better performance with SSR/SSG/ISR
- Multi-channel frontend from single BigCommerce backend
Catalyst
What It Is
BigCommerce's official Next.js reference storefront:
- Built on Next.js 14+ with App Router
- Uses GraphQL Storefront API for data
- Tailwind CSS for styling
- Full-featured: PLP, PDP, cart, checkout, customer account, search
- Designed as a starting point to fork and customize
Getting Started
npx create-catalyst-storefront@latest my-store
Prompts for:
- BigCommerce store URL
- Channel ID
- Storefront API token
Project Structure
my-store/
├── app/ # Next.js App Router pages
│ ├── (default)/ # Default locale group
│ │ ├── page.tsx # Homepage
│ │ ├── product/ # Product pages
│ │ ├── category/ # Category pages
│ │ ├── cart/ # Cart page
│ │ └── account/ # Customer account
│ └── layout.tsx # Root layout
├── client/ # BigCommerce API client
│ ├── queries/ # GraphQL queries
│ └── mutations/ # GraphQL mutations
├── components/ # React components
├── lib/ # Utilities
├── public/ # Static assets
├── .env.local # Environment variables
├── next.config.js # Next.js config
├── tailwind.config.js # Tailwind config
└── package.json
Key Environment Variables
BIGCOMMERCE_STORE_HASH=your_store_hash
BIGCOMMERCE_ACCESS_TOKEN=your_access_token
BIGCOMMERCE_CHANNEL_ID=1
BIGCOMMERCE_STOREFRONT_TOKEN=your_storefront_token
BIGCOMMERCE_CUSTOMER_IMPERSONATION_TOKEN=your_token
Data Fetching Patterns
Server Components (Recommended)
Fetch data in Next.js Server Components using the GraphQL client:
// app/product/[slug]/page.tsx
async function ProductPage({ params }: { params: { slug: string } }) {
const product = await getProduct({ path: `/${params.slug}` });
return <ProductDetail product={product} />;
}
Client-Side Fetching
For interactive features (cart, search-as-you-type):
- Use React hooks with the GraphQL Storefront API
- Storefront API token for unauthenticated requests
- Customer impersonation token for personalized data
Caching Strategy
- Static Generation (SSG) — product and category pages at build time
- Incremental Static Regeneration (ISR) — revalidate on interval or on-demand
- Server-Side Rendering (SSR) — cart, checkout, account pages
- Client-Side — search, cart updates, wishlist
Checkout in Headless
Embedded Checkout (Recommended)
Embed BigCommerce's checkout in your headless site:
- Create cart via API → get
redirect_urls.checkout_url
- Embed using
@bigcommerce/checkout-sdk embedCheckout()
- BigCommerce handles payment processing (no PCI scope)
Custom Checkout
Full API-driven checkout:
- Cart API → Checkout API → Orders API → Payments API
- Requires your own checkout UI
- Payment processing via Payments API (PCI implications if handling raw card data)
- Use tokenized payment methods to reduce PCI scope
Authentication in Headless
Customer Login
- Use the Customer Login API (JWT-based SSO) to create sessions
- Or implement custom auth and use Customer Impersonation Tokens for API access
- Catalyst includes built-in authentication flows
Session Management
- BigCommerce sessions are cookie-based on the BigCommerce domain
- For headless: use Customer Login API to set the cookie, then redirect to your domain
- Or manage auth entirely on your side and use impersonation tokens
Integration with Other Services
Composable Commerce Stack
BigCommerce + headless enables composable architecture:
- CMS: Contentful, Sanity, Strapi for content
- Search: Algolia, Bloomreach for product search
- Personalization: Dynamic Yield, Nosto for recommendations
- PIM: Akeneo, Salsify for product information
- OMS: for order management
Best Practices
- Start with Catalyst — fork and customize rather than building from scratch
- Use GraphQL Storefront API for frontend data fetching
- Use REST API for server-side operations (order management, catalog sync)
- Use Embedded Checkout to avoid PCI scope
- Implement ISR for product/category pages — balance freshness and performance
- Use customer impersonation tokens for personalized data
- Handle webhook events for real-time data sync
- Set up proper CORS configuration for Storefront API tokens
- Use environment variables for all credentials
Fetch the Catalyst documentation and BigCommerce headless guide for exact setup steps, GraphQL queries, and current best practices before implementing.
1---2name: bc-headless3description: Build headless commerce with BigCommerce — Catalyst (Next.js reference storefront), GraphQL Storefront API, server-side APIs, embedded checkout, and headless architecture patterns. Use when building decoupled storefronts or integrating BigCommerce as a headless backend.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/bc-headless7---89# BigCommerce Headless Commerce1011## Before writing code1213**Fetch live docs**:141. Fetch `https://www.catalyst.dev/` for Catalyst documentation152. Web-search `site:developer.bigcommerce.com headless` for headless guide163. Web-search `site:github.com bigcommerce catalyst` for Catalyst source and examples1718## Headless Architecture1920### What Headless Means for BigCommerce2122Decouple the frontend from BigCommerce:23- BigCommerce serves as the **commerce backend** — catalog, orders, customers, payments24- Your custom frontend handles **presentation** — React, Next.js, Vue, etc.25- Communication via **APIs** — GraphQL Storefront API and REST API26- Checkout via **Embedded Checkout** or **Custom Checkout** (Checkout API + Payments API)2728### Why Headless2930- Full frontend control (design, UX, performance)31- Use modern frameworks (Next.js, Remix, Astro)32- Composable architecture — mix BigCommerce with CMS, search, etc.33- Better performance with SSR/SSG/ISR34- Multi-channel frontend from single BigCommerce backend3536## Catalyst3738### What It Is3940BigCommerce's official Next.js reference storefront:41- Built on **Next.js 14+** with App Router42- Uses **GraphQL Storefront API** for data43- **Tailwind CSS** for styling44- Full-featured: PLP, PDP, cart, checkout, customer account, search45- Designed as a starting point to fork and customize4647### Getting Started4849```bash50npx create-catalyst-storefront@latest my-store51```5253Prompts for:54- BigCommerce store URL55- Channel ID56- Storefront API token5758### Project Structure5960```61my-store/62├── app/ # Next.js App Router pages63│ ├── (default)/ # Default locale group64│ │ ├── page.tsx # Homepage65│ │ ├── product/ # Product pages66│ │ ├── category/ # Category pages67│ │ ├── cart/ # Cart page68│ │ └── account/ # Customer account69│ └── layout.tsx # Root layout70├── client/ # BigCommerce API client71│ ├── queries/ # GraphQL queries72│ └── mutations/ # GraphQL mutations73├── components/ # React components74├── lib/ # Utilities75├── public/ # Static assets76├── .env.local # Environment variables77├── next.config.js # Next.js config78├── tailwind.config.js # Tailwind config79└── package.json80```8182### Key Environment Variables8384```85BIGCOMMERCE_STORE_HASH=your_store_hash86BIGCOMMERCE_ACCESS_TOKEN=your_access_token87BIGCOMMERCE_CHANNEL_ID=188BIGCOMMERCE_STOREFRONT_TOKEN=your_storefront_token89BIGCOMMERCE_CUSTOMER_IMPERSONATION_TOKEN=your_token90```9192## Data Fetching Patterns9394### Server Components (Recommended)9596Fetch data in Next.js Server Components using the GraphQL client:97```typescript98// app/product/[slug]/page.tsx99async function ProductPage({ params }: { params: { slug: string } }) {100 const product = await getProduct({ path: `/${params.slug}` });101 return <ProductDetail product={product} />;102}103```104105### Client-Side Fetching106107For interactive features (cart, search-as-you-type):108- Use React hooks with the GraphQL Storefront API109- Storefront API token for unauthenticated requests110- Customer impersonation token for personalized data111112### Caching Strategy113114- **Static Generation (SSG)** — product and category pages at build time115- **Incremental Static Regeneration (ISR)** — revalidate on interval or on-demand116- **Server-Side Rendering (SSR)** — cart, checkout, account pages117- **Client-Side** — search, cart updates, wishlist118119## Checkout in Headless120121### Embedded Checkout (Recommended)122123Embed BigCommerce's checkout in your headless site:1241. Create cart via API → get `redirect_urls.checkout_url`1252. Embed using `@bigcommerce/checkout-sdk` `embedCheckout()`1263. BigCommerce handles payment processing (no PCI scope)127128### Custom Checkout129130Full API-driven checkout:1311. Cart API → Checkout API → Orders API → Payments API1322. Requires your own checkout UI1333. Payment processing via Payments API (PCI implications if handling raw card data)1344. Use tokenized payment methods to reduce PCI scope135136## Authentication in Headless137138### Customer Login139140- Use the Customer Login API (JWT-based SSO) to create sessions141- Or implement custom auth and use Customer Impersonation Tokens for API access142- Catalyst includes built-in authentication flows143144### Session Management145146- BigCommerce sessions are cookie-based on the BigCommerce domain147- For headless: use Customer Login API to set the cookie, then redirect to your domain148- Or manage auth entirely on your side and use impersonation tokens149150## Integration with Other Services151152### Composable Commerce Stack153154BigCommerce + headless enables composable architecture:155- **CMS**: Contentful, Sanity, Strapi for content156- **Search**: Algolia, Bloomreach for product search157- **Personalization**: Dynamic Yield, Nosto for recommendations158- **PIM**: Akeneo, Salsify for product information159- **OMS**: for order management160161## Best Practices162163- Start with Catalyst — fork and customize rather than building from scratch164- Use GraphQL Storefront API for frontend data fetching165- Use REST API for server-side operations (order management, catalog sync)166- Use Embedded Checkout to avoid PCI scope167- Implement ISR for product/category pages — balance freshness and performance168- Use customer impersonation tokens for personalized data169- Handle webhook events for real-time data sync170- Set up proper CORS configuration for Storefront API tokens171- Use environment variables for all credentials172173Fetch the Catalyst documentation and BigCommerce headless guide for exact setup steps, GraphQL queries, and current best practices before implementing.