BigCommerce Headless Commerce: What You Rebuild Yourself

What BigCommerce headless commerce changes about your storefront

BigCommerce headless commerce splits your store into two separate pieces: BigCommerce stays the backend, holding your catalogue, orders, customer records and, if you choose to keep it, checkout, while a completely separate front end — a Next.js app, a different framework, whatever your team chooses to build — renders every page the shopper actually sees. Instead of BigCommerce’s own Stencil theme engine generating your storefront pages, your front end queries BigCommerce’s APIs directly and builds the UI itself.

That single change is bigger than it sounds, because Stencil isn’t just a template. It’s cart logic, checkout page rendering, search and filtering UI, and a theme customiser your merchandising team can use without touching code, all bundled together. Going headless doesn’t remove the backend functions those pieces call, but it does remove the interface BigCommerce built for them. You rebuild that interface yourself, in your own codebase, maintained by your own team, forever.

This article is for operators at $3M to $30M in revenue already running BigCommerce, evaluating whether headless is the right next step, or midway through a build and trying to work out what they’ve actually signed up for. It isn’t a pitch for going headless. Plenty of brands in that revenue range are better served staying on a well-built Stencil theme, and this article says so directly, including where that line sits.

What you need before you start a BigCommerce headless build

Before scoping anything, get honest answers to four questions, because the answers determine whether headless is even the right conversation.

Do you have a front-end engineering team, not just a developer who can install apps? A headless storefront is application development: routing, state management, API integration, caching, deployment pipelines. It is not theme customisation. If your current technical capacity is a freelancer who edits Stencil templates, headless is a different job, not a harder version of the same one.

What specific UI problem does a theme genuinely block you from solving? Not “more control” as an abstract goal — a concrete thing. A checkout flow that needs to embed a configurator mid-flow. A product page that needs real-time inventory across twenty locations rendered in a way Stencil’s templating can’t express. A content experience that blends editorial pages and product pages more tightly than a theme allows. If you can’t name the specific block, you probably don’t have the problem headless solves.

Who maintains this after launch? Not who builds it. A headless storefront doesn’t stop needing engineering time once it ships; every BigCommerce API change, every new payment method, every accessibility fix, every performance regression is now your team’s job, indefinitely, rather than something a theme update or an app handles.

What’s your actual traffic and catalogue size? A headless build’s performance and flexibility gains show up most at scale — large catalogues, high traffic, complex merchandising. Below that, a lot of the argument for going headless is theoretical.

Step 1: Decide which storefront you’re replacing, not just the theme

Headless isn’t all-or-nothing, and the first real decision is scope: are you replacing the entire storefront, or specific sections of it? BigCommerce supports a hybrid approach where some pages stay on Stencil and others are served by a separate front end, which is a materially smaller project than a full rebuild.

Common scoping choices: replace only the homepage and top-level content pages, which need the least commerce logic and the most editorial flexibility, while keeping category, product and checkout pages on Stencil. Or replace the full browse experience — category, filtering and product detail pages — while keeping BigCommerce’s Optimized Checkout as a hosted step, which avoids rebuilding payment and tax logic entirely. Or go fully headless end to end, which is the most expensive and highest-maintenance option and is rarely justified below real scale.

Write the scope down as a list of storefront sections, not as “headless: yes.” That list is what a build quote should be priced against, and it’s what tells you honestly how much you’re taking on.

Step 2: Rebuild cart and checkout logic yourself

If checkout is in scope for your headless build, this is the step with the most hidden surface area. Stencil’s cart and checkout pages handle line-item validation, discount code application, tax calculation triggers, shipping method selection and payment method rendering, all wired together and tested against BigCommerce’s backend by BigCommerce. A headless front end has to call the same underlying logic through the Checkout SDK or the Storefront API and rebuild every one of those interactions as its own UI.

The part teams underestimate is edge-case handling: what the cart does when an item goes out of stock between adding it and checking out, what happens when a discount code is valid on some line items but not others, how partial shipping availability is communicated when a cart spans multiple fulfilment locations. Stencil’s checkout has years of these edge cases already handled. A custom checkout UI starts from zero on all of them.

Keeping BigCommerce’s Optimized Checkout as a hosted page, even in an otherwise headless storefront, is the choice most teams should default to unless there’s a specific reason to rebuild checkout itself, precisely because of that edge-case cost. It’s the one piece of the storefront where the cost of getting an edge case wrong — a customer charged incorrectly, a tax miscalculation, a failed payment retry that doesn’t retry — is highest, and where BigCommerce’s own hosted version has already absorbed that cost of correctness.

Step 3: Rebuild site search and merchandising

Stencil ships with built-in product search and category filtering. Going headless removes that UI, though not necessarily the underlying data — you can still query BigCommerce’s catalogue data through its APIs, but the search relevance logic, autocomplete, filter facets and sort options are now your front end’s job to build and tune.

For a small catalogue, a straightforward implementation against the Storefront API’s product search may be enough. For a large or fast-changing catalogue, most headless BigCommerce builds end up integrating a dedicated search service rather than building relevance ranking from scratch, because search quality directly affects conversion and building good relevance tuning in-house is a specialised, ongoing job, not a one-time build. Either way, budget for search as its own line item, not as something that comes free with the API connection.

Merchandising — featured collections, cross-sells, manually curated product groupings — sits in the same category. Stencil’s theme editor lets a merchandiser make these changes without a deploy. A headless storefront needs either a content layer that gives merchandisers similar self-service control, or every merchandising change becomes an engineering ticket. Skipping this consideration is one of the most common reasons headless builds quietly slow a marketing team down after launch, even though the storefront itself is faster.

Step 4: Rebuild product listing and filtering pages

Category and product listing pages look simple until you rebuild the logic behind them: pagination, sort order, filter combinations, out-of-stock handling, and how variant options are represented when a product has many. Stencil handles all of this server-side, tied directly to BigCommerce’s catalogue rules. A headless front end has to replicate the same rules by querying the Storefront API’s catalogue and category endpoints and implementing filtering logic client-side or through a middle layer.

The setting most teams get wrong here is filter-and-inventory interaction: whether a filter option that would return zero in-stock results is hidden, shown greyed out, or shown normally. Stencil’s default behaviour handles this consistently across every category. A custom build has to make and implement that decision explicitly, category by category, and it’s easy to ship inconsistent behaviour across different parts of the site because different developers built different sections at different times.

Step 5: Wire up the BigCommerce APIs your storefront needs

At minimum, a headless BigCommerce storefront typically integrates BigCommerce’s GraphQL Storefront API for catalogue and cart data, and the Checkout SDK if checkout is in scope. Beyond that, most builds also need the Catalog API or Admin-side APIs for anything the storefront-facing API doesn’t expose, webhooks for keeping the front end’s cache in sync with backend changes like inventory updates or price changes, and authentication handling for customer accounts if those are part of the headless scope.

Webhooks matter more in a headless build than in a themed one, because a themed store renders fresh from BigCommerce’s own data on every request, while a headless front end almost always caches data for performance. That cache needs an invalidation strategy: when a product’s price or stock changes in BigCommerce, something has to tell your front end’s cache to refresh. Get this wrong and the storefront shows stale prices or lets a shopper add an out-of-stock item to cart, which is a worse experience than the slower, always-fresh Stencil page it replaced.

Check BigCommerce’s own current developer documentation for exactly which APIs are exposed and how they’re versioned before scoping this step; API surfaces and rate handling change over time, and a guide written today can be out of date by the time you build against it.

Step 6: Set up preview, staging and content publishing without the page builder

Stencil’s theme customiser gives non-technical staff a live preview and a publish button. Headless removes that entirely unless you deliberately rebuild an equivalent, usually by pairing the storefront with a content management layer that gives marketing and merchandising staff a way to edit copy, images and layout without opening a pull request.

Skipping this step is common, and the cost shows up weeks after launch, not on launch day: every homepage banner change, every seasonal copy update, every landing page for a campaign becomes a developer task instead of something a marketer does in an afternoon. Budget the content layer and its editorial workflow as part of the initial build, not as a follow-up phase, because retrofitting editorial control onto a storefront that was built without it is close to a second project.

The step most teams get wrong

Teams that go headless on BigCommerce most often underestimate one specific thing: Stencil’s checkout does a large amount of validation and error handling that’s invisible until you have to build it yourself. Field-level validation, retry behaviour on a failed payment, handling for a session that expires mid-checkout, correct behaviour when a customer’s cart total changes between page load and submission — all of it ships in Stencil, tested against real traffic for years, and none of it transfers automatically to a custom checkout UI.

If you take one thing from this article: default to keeping BigCommerce’s Optimized Checkout hosted, even in an otherwise fully headless storefront, unless there is a specific, named reason it can’t meet your requirements. The UI flexibility gained by rebuilding checkout yourself is rarely worth the edge-case risk, and it’s the single most expensive piece of the storefront to get subtly wrong.

How to verify a headless BigCommerce build is actually ready

Before launch, check four things directly rather than trusting that the build is complete because the visible pages look right.

Load-test the catalogue pages under a traffic pattern close to your actual peak, not just a handful of manual page loads, because caching and API query performance issues often only appear under concurrent load, and a headless front end has no theme-level performance floor protecting it the way Stencil does.

Walk through every discount code type, shipping method combination and out-of-stock scenario in checkout manually, whether checkout is custom-built or the hosted Optimized Checkout embedded in a custom flow, because these are exactly the edge cases the checkout rebuild raises as the highest-risk area.

Confirm the cache invalidation strategy actually fires: change a product’s price or stock level in BigCommerce’s control panel and time how long it takes to reflect on the live storefront. If that number is longer than your business can tolerate — a flash sale, a price correction — that’s a gap to fix before launch, not after.

Hand the content layer to whoever will actually use it — a marketer, not a developer — and have them publish a real change without help. If they can’t, the editorial workflow isn’t finished, whatever the build plan says.

What headless commerce on BigCommerce costs that the platform fee doesn’t

BigCommerce’s own platform fee covers hosting, the backend, and Stencil if you use it. Going headless doesn’t change that fee, but it adds cost lines that a themed store doesn’t carry, and naming them matters more than a total figure would, because the total varies enormously by scope and by whether you build in-house or hire an agency.

The front-end hosting and infrastructure for your custom storefront is a separate bill from BigCommerce’s own hosting, whether that’s a hosting platform for a JavaScript framework, a CDN, or both. The initial build itself — every step above, scoped and priced — is the largest one-time cost, and it scales directly with how much of the storefront you’re replacing, which is why scoping the storefront sections up front is also, indirectly, a budgeting decision. Ongoing engineering maintenance is the cost most brands underweight: someone has to own this codebase permanently, patching dependencies, handling BigCommerce API changes, and building new features that a theme update or an app would otherwise have delivered for free. And a content or search service, if you add one in Steps 3 and 6, is usually its own recurring line item on top of BigCommerce’s fee.

A single total figure isn’t honest here, because these costs depend on your scope, your team’s rates and your existing infrastructure. Ask any agency or contractor quoting the work to break the estimate down against the storefront-section list, not as one lump sum, so you can see which pieces are driving the cost.

Who should not go headless on BigCommerce

If your team’s current technical capacity tops out at theme customisation and app installation, headless is not a stretch goal, it’s a different discipline, and taking it on without hiring for it usually produces a storefront that launches thin and then stalls, because nobody has the capacity to build the parts that were deprioritised to hit launch.

If you can’t name a specific storefront problem a theme blocks you from solving, you’re evaluating headless because it sounds like the more sophisticated choice, not because you have a problem it solves. That’s a reason to stay on Stencil, invest the same budget in a genuinely custom theme, and revisit headless once a concrete requirement appears.

And this isn’t a path for a brand below the roughly $3M revenue mark or one without a paid, capable ecommerce platform already in place. Below that floor, the maintenance burden of a second codebase, indefinitely, outweighs almost any UI flexibility gained, and a well-built Stencil theme covers the large majority of what a brand at that stage genuinely needs from its storefront.

For a scaling brand that does have the traffic, the catalogue complexity and the engineering capacity, our scaling brands work is built around exactly this kind of decision: knowing which infrastructure investment earns its cost at your actual scale, rather than at the scale a case study was written about.

What breaks after launch that nobody budgets for

Three things tend to surface in the months after a headless BigCommerce launch, none of them visible during the build itself.

BigCommerce changes an API your storefront depends on, and because your front end isn’t running inside BigCommerce’s own release process, you find out when something breaks rather than through a heads-up. Subscribe to BigCommerce’s developer changelog and treat API version changes as a recurring maintenance task, not a one-time integration.

Content velocity drops. Even with a dedicated content layer in place, a headless workflow is usually slower for quick copy changes than Stencil’s theme customiser was, because there’s more moving infrastructure between an edit and it going live. Marketing teams that were used to same-day changes on Stencil often need to adjust expectations, or the content layer needs further investment to close that gap.

And the front-end codebase accumulates the same technical debt any application does: dependencies go out of date, the original developers move on, and undocumented decisions become mysteries. A themed BigCommerce store inherits BigCommerce’s own maintenance; a headless storefront inherits yours, on your own engineering roadmap, competing for the same sprint capacity as everything else you build.

Keeping a headless BigCommerce storefront reliable after launch, especially the API sync, cache invalidation and webhook handling that Step 5 sets up, is fundamentally an ops automation problem: pipelines that move data between systems and need monitoring so a stale cache or a broken webhook gets caught before a customer notices. That’s the scope our ops automation work addresses directly, rather than treating a headless build as finished the day it ships.