Most headless commerce content is written by agencies that charge $50,000 to build what they're describing. That's a conflict of interest worth naming upfront.
I've run two stores past $1M ARR on traditional platforms, then rebuilt one of them headless. The rebuild took four months, cost roughly $28,000 in dev time, and delivered real wins — but also real headaches I didn't see coming. So this is headless commerce architecture explained from the operator's chair, not the consultant's pitch deck.
This post covers what the architecture actually looks like under the hood, where the performance and flexibility gains are real versus theoretical, what it costs at SMB scale, and how to decide whether you should touch it at all.
What "Headless" Actually Means (Skip the Jargon)
A traditional e-commerce platform — Shopify, WooCommerce, BigCommerce — couples the front end (what customers see) to the back end (catalog, cart, checkout, orders) in one monolithic system. Change the storefront, you're working inside the platform's templating engine. Change the back end, you're fighting the same box.
Headless decouples those two layers. Your back end — the commerce engine — exposes everything through APIs. Your front end is a completely separate application, usually built in Next.js or Nuxt.js, that calls those APIs to fetch products, prices, and cart state. The two systems talk over HTTP; neither cares what the other is built with.
That's it. That's the whole idea. Everything else — composable commerce, MACH architecture, "experience-first" — is marketing vocabulary layered on top of this one simple split.
The practical result: your storefront is just a web app. You can deploy it on Vercel or Cloudflare Pages, cache aggressively at the CDN edge, and render pages in under 200ms globally without paying for a Shopify Plus plan at $2,300/month.
The Four Components You Need to Wire Together
When you go headless, you're no longer buying one platform. You're assembling a stack. Here's what that stack looks like at minimum viable scale:
1. Commerce back end (the API layer) This is your product catalog, inventory, pricing, cart, and checkout. Common choices at SMB scale: Medusa.js (open-source, self-hosted, free to run on a $20/month VPS), Shopify Headless (still $79–$2,300/month depending on plan, but you drop their Liquid templating), or BigCommerce's headless offering.
Medusa 2.0, released in late 2024, rewrote the module system entirely and is genuinely production-ready now. I'd start there for a greenfield build under $500K GMV.
2. Front-end framework Next.js 14+ with the App Router is the current default for headless storefronts. It gives you React Server Components, which means you can fetch product data on the server, stream it to the client, and avoid the waterfall API calls that made early headless stores feel sluggish.
Nuxt 3 is equally capable if your team lives in Vue. Don't let anyone tell you one is objectively better — pick what your developers already know.
3. Content layer (optional but usually necessary) Headless commerce and headless CMS often get conflated. They're separate problems. If you need rich editorial content — brand pages, buying guides, blog posts — you'll want a CMS like Sanity, Contentful, or Hygraph sitting alongside your commerce back end. Sanity's free tier handles most SMBs. Contentful's free tier caps at 25,000 API calls/month, which you'll blow through fast.
4. Search and discovery Platform-native search is usually the first thing you lose going headless. Algolia (starts at $0 for under 10,000 records, then ~$1/1,000 records) or Typesense (open-source, self-hostable) fills that gap. For a catalog under 5,000 SKUs, Typesense on a $6/month Fly.io instance is hard to argue with.
Where the Performance Gains Are Real
Here's what headless actually delivers versus what it promises.
Real: Edge-cached static pages. A product page built with Next.js, statically generated at build time and served from Vercel's edge network, will load in 80–120ms for most US visitors. A Shopify Liquid page, rendered server-side in their infrastructure, typically runs 400–900ms TTFB. That gap is measurable in conversion rate — Google's own data puts a 100ms delay at roughly 1% conversion loss.
Real: Full control over the checkout experience. On standard Shopify, your checkout is Shopify's checkout. You can customize colors and add a few fields, but you can't restructure the flow, add a custom upsell modal between cart and payment, or integrate a non-standard payment provider without Shopify Plus. Headless removes that ceiling.
Real: Multi-channel from one back end. Same API serves your web storefront, your mobile app, your kiosk, your B2B portal. You build the commerce logic once.
Overstated: Developer velocity. Every headless proponent says "move faster." In practice, you move faster on features that require custom UI and slower on everything else. Updating a shipping rate? Three API calls and a cache invalidation instead of one settings page click. Headless trades platform constraints for infrastructure complexity.
Overstated: Cost savings. At under $50K GMV/month, you will almost certainly spend more on headless — in dev time, hosting, and tooling — than you save on platform fees. The math flips somewhere around $100K–$200K GMV/month, depending on your Shopify plan tier and how much you're currently paying for apps that a custom build would replace.
A Minimal Working Example: Medusa + Next.js
Here's a stripped-down product fetch in a Next.js App Router page component talking to a local Medusa instance. This is the pattern you'll repeat hundreds of times in a headless build.
// app/products/[handle]/page.tsx
import { notFound } from 'next/navigation'
async function getProduct(handle: string) {
const res = await fetch(
`${process.env.MEDUSA_BACKEND_URL}/store/products?handle=${handle}`,
{
headers: { 'x-publishable-api-key': process.env.MEDUSA_API_KEY! },
next: { revalidate: 3600 }, // ISR: revalidate every hour
}
)
if (!res.ok) return null
const { products } = await res.json()
return products[0] ?? null
}
export default async function ProductPage({
params,
}: {
params: { handle: string }
}) {
const product = await getProduct(params.handle)
if (!product) notFound()
return (
<main>
<h1>{product.title}</h1>
<p>{product.description}</p>
<p>${(product.variants[0].prices[0].amount / 100).toFixed(2)}</p>
</main>
)
}
The next: { revalidate: 3600 } option is doing important work here. It tells Next.js to cache this response at the CDN for one hour and regenerate it in the background on the next request after expiry (Incremental Static Regeneration). Your product page loads from cache in milliseconds; your Medusa server handles maybe one request per hour per product instead of one per visitor.
For a real build you'd add error boundaries, loading states, and a cart context — but this is the skeleton everything else hangs on.
When Headless Is the Wrong Call
I'd talk you out of headless in any of these situations:
You're under $30K GMV/month. The infrastructure overhead isn't worth it. A well-configured Shopify store with a fast theme (Dawn scores 85+ on PageSpeed out of the box) will serve you fine. Spend that dev budget on ads or email flows instead.
You don't have a developer on staff or on retainer. Headless breaks constantly in small, annoying ways — a Medusa update changes an API response shape, a Next.js upgrade deprecates a caching behavior, your Algolia index goes stale. You need someone who can fix these things in under two hours, not in three days when your agency gets back to you.
Your differentiation isn't in the storefront. If your competitive advantage is product selection, pricing, or brand story — not a uniquely custom shopping experience — headless gives you complexity without payoff. I've seen stores do $5M/year on a $79/month Shopify plan with a $300 theme. Don't let architecture envy pull you away from what's working.
You need to move fast on merchandising. Marketers and merchandisers can update a Shopify store without touching code. In a headless setup, "change the homepage banner" might require a CMS update, a cache purge, and a Slack message to the dev who owns the component. Build a proper CMS integration before you go live, or your marketing team will hate you.
Comparing Your Back-End Options at SMB Scale
| Commerce Engine | Pricing | Hosting | Headless-first? | Best for |
|---|---|---|---|---|
| Medusa.js 2.0 | Free (OSS) | Self-hosted (~$20–$50/mo VPS) | Yes | Greenfield builds, custom logic |
| Shopify Headless | $79–$2,300/mo | Managed | Partial (Liquid still exists) | Teams already on Shopify ecosystem |
| BigCommerce | $39–$399/mo | Managed | Yes (GraphQL Storefront API) | Mid-market, B2B features needed |
| Commerce.js | $99–$499/mo | Managed | Yes | Rapid prototyping, smaller catalogs |
| Vendure | Free (OSS) | Self-hosted | Yes | TypeScript shops, complex B2B |
Medusa wins on cost and flexibility at the low end. Shopify wins if you need their ecosystem (Shop Pay, Shopify Payments, their app store) and don't want to manage infrastructure. BigCommerce is underrated for B2B headless — their native B2B features beat Shopify's at the $299/month tier.
If you want a deeper look at how these platforms stack up outside the headless context, the Shopify alternatives breakdown on this site covers the full picture.
Headless Commerce Architecture Explained: The Honest Summary
Headless commerce architecture explained plainly: you're trading a walled garden for an open field. The open field has better views and more room to build, but you're also responsible for the fences, the drainage, and fixing the gate when it breaks.
At $100K+ GMV/month, with a developer available and a genuine need for custom experience, it's the right trade. Below that threshold, for most stores, it's premature optimization dressed up as innovation.
Here's what I'd actually do: if you're curious about headless but not ready to commit, spin up a Medusa 2.0 instance locally this weekend — it takes about 20 minutes with their CLI — and build one product page in Next.js against it. You'll know within a day whether the complexity feels manageable or overwhelming for your team. That's better data than lessons from 20 years of software engineering, including this one.
If you're evaluating whether to go headless or stay on a managed platform, the total cost of ownership comparison is worth reading before you make any commitments.
Considering a headless build? The storehabit.com newsletter covers real implementation notes — stack decisions, cost breakdowns, and what broke — from operators who've shipped it.