Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 28 ยท Headless Commerce

Headless Storefronts

Decide when headless commerce fits BigCommerce, then learn channels and sites, Catalyst, Next.js with GraphQL, cart redirects, SEO and caching with revalidation.

A normal BigCommerce storefront is rendered by the platform: a Stencil theme turns catalog data into HTML on BigCommerce's servers. A headless storefront splits that apart. BigCommerce keeps the catalog, cart, checkout, customers and orders, and your own application renders the pages and talks to the platform through APIs. The "head" (the presentation layer) is yours; the "body" (commerce) stays with the platform.

That freedom costs real work. You take over routing, caching, SEO, accessibility, image handling and uptime for the part customers see. This lesson helps you decide whether it is worth it, then walks through how the pieces connect: channels and sites, the Catalyst starter, Next.js with the GraphQL Storefront API, carts and checkout redirects, and the caching rules that keep a headless site fast. Real code needs a store and tokens, so it is read-only. The runnable stand-ins are a cache-and-revalidate data layer and a product-page metadata builder in plain Node.js.

When headless fits (and when it does not)

Headless is a tool, not an upgrade. It fits when:

  • The storefront must live inside a larger product, such as an app, a content site or a marketplace, with one design system and one codebase.
  • You need a front end framework experience: React Server Components, custom animation, or a team that already ships Next.js.
  • One store feeds several front ends, such as a web shop, a kiosk and a mobile app.
  • Performance work needs control that a theme cannot offer, such as edge rendering or fine-grained caching.

It is usually the wrong choice when:

  • A Stencil theme plus Widgets and Page Builder already gives you the look you want.
  • The team is small and has no front-end engineers. Merchants lose editing tools they take for granted, and every small change becomes a deploy.
  • You would be rebuilding features the platform gives for free: faceted search pages, product comparison, wish lists, account pages.

A useful rule: if you cannot name a requirement a theme cannot meet, stay with a theme. Choosing a platform and an architecture is also covered in Choosing a Platform.

Channels and sites

In Platform Architecture you met channels: a channel is a place where products are sold, and each channel has its own product assignments, currency settings and (for storefronts) one or more sites with URLs. A headless storefront is simply a channel whose site is served by your application instead of a Stencil theme. You create a channel of type storefront, assign the products it may sell, and register the site's URL so that links, redirects and checkout know where to send customers.

Two consequences to remember:

  • Product visibility is per channel. A product not assigned to your headless channel will not show up in that channel's GraphQL queries, even though it exists in the catalog.
  • Checkout still belongs to BigCommerce. Your site builds carts, then sends customers to a hosted checkout URL tied to the channel. You never handle card numbers yourself, which keeps you out of most PCI scope.

Catalyst and Next.js

Catalyst is BigCommerce's open-source starter for headless storefronts. It is a Next.js application that talks to the GraphQL Storefront API and ships with product pages, category pages, search, a cart and account screens. You clone it, set environment variables, and own the code from there. Because it is only an application, you can read how it works, replace pieces, and deploy it to any host that runs Next.js.

The shape of a typical product page in a Next.js app router project looks like this (read-only, simplified):

TypeScript
// app/product/[slug]/page.tsx  (read-only sketch)
const PRODUCT_QUERY = /* GraphQL */ `
  query Product($path: String!) {
    site {
      route(path: $path) {
        node {
          ... on Product {
            entityId
            name
            sku
            path
            prices { price { value currencyCode } }
            defaultImage { url(width: 800) altText }
          }
        }
      }
    }
  }
`;

export default async function ProductPage({ params }: { params: { slug: string } }) {
  const res = await fetch(process.env.BIGCOMMERCE_GRAPHQL_URL!, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.BIGCOMMERCE_STOREFRONT_TOKEN}`,
    },
    body: JSON.stringify({ query: PRODUCT_QUERY, variables: { path: `/${params.slug}/` } }),
    next: { revalidate: 300, tags: ['products'] },
  });
  const { data } = await res.json();
  // render data.site.route.node ...
}

Three details matter. The query asks only for fields the page uses (see GraphQL Storefront API). The token is a storefront token, scoped to the storefront, and it lives in a server environment variable. The next options tell Next.js to reuse the response for five minutes and to label it with a tag, so you can refresh it early. That last idea, cache with revalidation, is the heart of headless performance, and we will build it from scratch below.

flowchart LR
    B["Browser"] --> N["Your Next.js app<br/>(pages, cache)"]
    N -->|"GraphQL<br/>storefront token"| G["BigCommerce<br/>GraphQL API"]
    N -->|"redirect URL"| C["Hosted checkout"]
    W["Webhook:<br/>product updated"] -->|"revalidate tag"| N

Your app renders and caches; BigCommerce supplies data, checkout and change notifications.

Carts and checkout redirects

A headless cart can live in the GraphQL API (a createCart mutation, then addCartLineItems) or be created server-to-server with the REST Carts API, covered in Carts and the Checkout API. Either way, the cart has an ID that you remember for the shopper, usually in an HTTP-only cookie. When the customer presses "Checkout", you ask for redirect URLs for that cart and send the browser to the checkout one. The redirect also carries the right channel context so the order is recorded against your storefront.

Keep these habits:

  • Store only the cart ID in the cookie, never prices. Prices come from the platform each time.
  • Treat the cart as expired when the platform says it no longer exists, and create a new one without crashing the page.
  • Never trust a price or discount sent from the browser. The platform recalculates everything; see Cart Design.

SEO and caching

A server-rendered Next.js page can be indexed well, but only if you do the work a theme did for you: titles and descriptions, canonical URLs, structured data, sitemaps, and redirects when a product's path changes (see E-commerce SEO). Product pages should carry Product structured data with the price and availability, built from the same data used to render the page.

Caching has two layers. The data cache stores API responses inside your app (what revalidate and tags control). The page or CDN cache stores rendered HTML at the edge. Both can show stale prices if you cache for too long, so the usual design is:

  1. Cache catalog responses for minutes, and category listings a little less.
  2. Never cache anything per customer: carts, prices for a signed-in group, account pages.
  3. Subscribe to webhooks such as product-updated events and revalidate by tag immediately, so a price change reaches shoppers in seconds without lowering the cache time for everyone.

A cache with revalidation

The stand-in below is a tiny data layer with the same ideas: a time-to-live, tags, and a revalidateTag call. Time is a variable we advance by hand, so the output is repeatable. The origin function plays the part of the GraphQL API and counts how often it is called. The real Next.js cache is more sophisticated; this shows the principle.

Node.js Data layer with TTL and tag revalidation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The shopper sees the old price at 61 seconds, which is the cost of caching. The webhook and revalidateTag fix that immediately, and the origin was called only three times for five requests. That ratio is what keeps a busy headless store fast and keeps API rate limits comfortable.

Product page metadata

The second stand-in builds what a product page must put in its <head>: a title, description, canonical URL and JSON-LD structured data. It also escapes < in the JSON so a product name cannot close the script tag. The product data is invented.

Node.js Build SEO tags and JSON-LD for a product

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice the name with angle brackets: it is escaped as text in the title, and as < inside the JSON. The real Catalyst code uses framework helpers for metadata, but the safety rule is the same.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which situation is the strongest reason to go headless?

    Headless pays off when you need control a theme cannot give, such as embedding the shop in a bigger application. Card data stays with the platform, and a team without front-end skills will struggle.
  2. 2. Why might a product exist in the catalog but not appear in your headless storefront queries?

    Product availability is per channel. Assign the product to the headless channel and it becomes visible there.
  3. 3. What is the purpose of revalidating a cache tag when a product-updated webhook arrives?

    Tag revalidation lets you keep a long cache time for speed while still pushing important changes to shoppers quickly.
  4. 4. What should the cart cookie contain?

    Store an identifier and fetch the cart from the platform, which recalculates prices and discounts. Prices from the browser must never be trusted.

Summary

  • Headless means your own app renders the storefront while BigCommerce provides catalog, cart, checkout and orders through APIs.
  • Choose it for a concrete requirement a theme cannot meet; otherwise a Stencil theme is faster and cheaper to maintain.
  • A headless storefront is a channel with a site URL; product assignment is per channel.
  • Catalyst is the open-source Next.js starter that uses the GraphQL Storefront API with a server-side storefront token.
  • Carts live on the platform; keep only the cart ID, and send customers to the redirect URL for checkout.
  • Cache catalog data, never per-customer data, and use webhooks to revalidate by tag.
  • You own SEO: titles, canonical URLs, structured data, sitemaps and redirects.

Next: Testing Apps and Themes