Building a Headless E-Commerce SaaS: Architecture and Test Plan

A headless e-commerce SaaS splits a fast, cached storefront from a commerce API that owns the catalogue, cart, orders and payments. The storefront renders from cached data; the API stays the source of truth for price and stock. Build it when you need a custom buying experience or multiple front ends. Test it in three layers: unit, API and end-to-end.

If you would rather have it built and tested for you, see how RAITHub would build this below. First, the architecture and the test plan.

What does "headless" actually mean here?

In a traditional store the front end and the commerce logic ship as one application. Headless separates them: the storefront is its own app that talks to a commerce API over HTTP, so you can rebuild the buying experience, add a second front end, or render pages statically without touching the engine behind it. The trade-off is that you now own the seam between the two, and most headless bugs live in that seam. Whether the move is even worth it for a given store is covered in when to move from Shopify to headless; this post assumes you have decided to build one as a SaaS.

What does the architecture look like?

Layer	Owns	Typical stack	Fails when
Storefront	Rendering, caching, SEO, the buying UX	Next.js, a CDN, incremental or static rendering	It trusts a cached price or stock figure that has changed
Commerce API	Catalogue, cart, orders, payments, the source of truth	Node/TypeScript, PostgreSQL, Prisma or SQL	Price or stock is computed in more than one place
Cache and search	Fast reads of the catalogue	CDN, Redis, a search index	Invalidation is missed, so buyers see stale data
Webhooks and jobs	Payment events, stock sync, emails	Signed webhooks, a job queue	Events arrive out of order or more than once

As a SaaS, the commerce API is multi-tenant: many stores share one platform and none may read another's data. That makes tenant isolation a first-class concern, the same as any B2B SaaS (multi-tenant SaaS platforms), and it decides your data model early (database-per-tenant vs shared schema).

Where does a headless store usually break?

Three places, all in the seam between storefront and API:

• Stale cache. The storefront shows a price or stock figure the API has since changed. The fix is to treat cached data as a hint and re-check price and stock on the server at the moment of purchase, never trusting what the client sends.
• Price computed twice. If the storefront and the API both calculate a total, they drift. Compute price in one place (the API) and have the storefront display it, so there is one answer to test.
• Webhook ordering and retries. A payment-succeeded event can arrive before, after or twice relative to your own order creation. Make every handler idempotent so a repeated or late event is safe (idempotency in API design).

What is the test plan?

Shape it like any SaaS: many fast unit tests, a strong API layer, a few end-to-end journeys (the test pyramid for a SaaS). The headless twist is that the storefront and API are tested both apart and together.

Layer	What to cover in a headless SaaS
Unit	Pricing, discounts, tax, currency rounding, cart rules, plan limits per store
API	Tenant isolation, server-authoritative price and stock, idempotent checkout and webhooks, catalogue contract
End-to-end	Browse, add to cart, checkout with a test card, order confirmation, reorder
Non-functional	Core Web Vitals on the storefront, cache invalidation, a light load test on the API

The one test teams skip in headless is the server re-check. Prove that a cart which sends an old price or an out-of-stock item is rejected by the API, not accepted because the storefront showed it:

// tests/api/server-authoritative-price.spec.ts
import { test, expect } from '@playwright/test'
import { tokenFor, currentPrice } from './helpers'

test('checkout uses the API price, not the client price', async ({ request }) => {
  const token = await tokenFor('buyer@store-a.test')
  const res = await request.post('/api/checkout', {
    headers: { Authorization: 'Bearer ' + token },
    data: { sku: 'SKU-1', clientPrice: 1 }, // buyer tampers with the price
  })
  const order = await res.json()
  expect(order.unitPrice).toBe(await currentPrice('SKU-1')) // server wins
})

How do you keep the storefront fast without serving stale data?

Cache catalogue reads hard, and keep price and stock live at the point of purchase. Google's web.dev thresholds for a good experience are Largest Contentful Paint at 2.5 seconds or less and Interaction to Next Paint at 200 milliseconds or less (web.dev, Web Vitals); a cached, statically rendered catalogue meets them easily. Put a Core Web Vitals budget in CI so a slow component fails the build, and test cache invalidation: change a price in the API and assert the storefront reflects it within your target window. The broader front-end method is in the Core Web Vitals guide.

Buy, build or hire?

Option	What you get	Choose this when
A hosted headless platform	A commerce API and SDKs, you build the storefront	Your commerce rules are standard and you want to own only the front end
A monolithic store platform	Front end and engine in one, themed	A single standard store; headless adds cost you do not need yet
A custom headless SaaS build	Your own API and storefront, multi-tenant	You sell the platform to many stores, or your pricing, credit or local rules are the product
A managed QA team on your build	The unit, API and end-to-end suites gated in CI	You have the platform but the seam between storefront and API is untested

How long does a first version take?

A focused first release of a headless commerce SaaS typically takes 4 to 6 weeks at a fixed scope for one storefront and the core API (catalogue, cart, checkout, orders), then phases for multi-store onboarding, search and reporting. Backend-heavy work such as payments, stock sync and reconciliation sits in the 6 to 12-week range. The main risk of building it yourself is under-testing the seam: the storefront looks finished while stale cache and client-trusted prices wait to surprise you in production.

Why RAITHub for this

RAITHub builds on Next.js, TypeScript and PostgreSQL, the common headless stack. TheSkinProof, the founder's own venture, runs 217 API endpoints with server-authoritative pricing and per-variant stock inside the order transaction, and 750+ tests. Sundor Skin enforces tenant isolation with row-level security and a security suite that tries to read other buyers' data. The same approach fits a headless SaaS: see how RAITHub builds e-commerce platforms, the SaaS development service, and the eCommerce industry page.

When you don't need us

• You run one standard store. A mainstream platform or a lightly themed monolith is cheaper and enough.
• You only need a storefront on a hosted commerce API. Build the front end; the API vendor tests the engine.
• Your procurement requires a SOC 2 or ISO 27001 vendor. RAITHub is not certified, though it builds the controls your auditor tests.

How RAITHub would build this

• Scope: a multi-tenant commerce API (catalogue, cart, checkout, orders, payments) with server-authoritative price and stock; a Next.js storefront with a Core Web Vitals budget; signed, idempotent webhooks; tenant isolation tested on every build.
• Timeline: a first storefront and core API in 4 to 6 weeks at fixed scope; payments, stock sync and multi-store onboarding in the 6 to 12-week range, delivered in phases.
• What you receive: the unit, API and end-to-end suites gated in CI, architecture diagrams and runbooks, the IP assigned to you and an NDA as standard.
• Ways to buy it: a fixed-scope first release, then a dedicated monthly team as the platform grows, or a QA plan if you only need the test suite.
• Next step: a free 15-minute technical audit, then a fixed written quote.

See the QA as a Service page, or book the free 15-minute audit.

Documentation checked on 10 October 2026.

Frequently asked questions

What is a headless e-commerce SaaS?

A platform that separates a fast, cached storefront from a commerce API behind it, offered as software many stores can use. The storefront renders quickly from cached data; the API owns catalogue, cart, orders and payments and stays the single source of truth for price and stock.

When is headless worth the extra complexity?

When you need a custom buying experience, multiple front ends, or you sell the platform to many stores. For a single standard store, a monolithic platform is cheaper and the headless seam is cost you do not need yet.

Where do headless stores usually break?

In the seam between storefront and API: stale cached prices or stock, price computed in two places that drift, and webhook events that arrive late, out of order or twice. The fixes are server-authoritative price and stock at purchase, a single pricing function, and idempotent handlers.

How do you test a headless commerce platform?

In layers: unit tests for pricing and rules, API tests for tenant isolation and server-authoritative money paths, a small end-to-end set for the buying journeys, and a Core Web Vitals budget plus cache-invalidation tests for the storefront.

How long does it take to build one?

A first storefront and core API typically take 4 to 6 weeks at a fixed scope. Payments, stock sync, reconciliation and multi-store onboarding are backend-heavy and sit in the 6 to 12-week range, delivered in phases.