Headless Commerce: What You Gain and What You Take On

A retailer with a working store on a mature platform decides to go headless. The pitch is reasonable: own the front end, ship pages without fighting a theme layer, serve the site and the app from one catalogue. Some way into the project the storefront is genuinely faster and genuinely nicer, and most of the team’s capacity is going into rebuilding things the old platform did for nothing.

None of that means the decision was wrong. It means the decision was priced wrong. Headless commerce is not a performance upgrade with a better developer experience attached. It is a transfer of responsibility: you take ownership of every capability that used to arrive bundled, and the bundle is always larger than the architecture diagram suggests.

So this piece is about what actually transfers. Checkout, search, promotions and the integration surface are the four that surprise teams, in roughly that order of cost. The question is not whether headless is better, but whether you want to own the parts it hands you. If you are weighing this against a serious tidy-up of what you already have, when to rewrite instead of refactor is the question that comes first.

What headless commerce actually means

Strip the marketing away and the definition is small. The storefront, meaning the thing a shopper sees, is a separate application from the commerce engine, meaning the thing that holds products, carts, prices, stock and orders. They talk over an API. That is the entire architecture.

Everything else is a consequence of it. You can render the storefront however you like, because it is your code. You can put the same catalogue behind a mobile app, a marketplace feed or an in-store screen, because none of them needs a theme. You can upgrade the two halves on separate schedules, which is either freedom or coordination overhead depending on the week you ask.

The word the market reaches for now is composable, which is the same idea extended: search from one vendor, content from another, payments from a third, promotions from a fourth, stitched together by code you own. That is a real architecture with real advantages. It is also a supply chain, and every link in it is a renewal date, a status page and somebody else’s roadmap.

The part of the promise that holds

Much of the pitch is true. It is worth being precise about which parts, because the true parts are what you are buying and the rest is decoration.

Front-end freedom is real. When the storefront is your own application, a design change is a code change rather than an argument with a template system, and the people who write the front end stop being limited to what a theme was willing to allow. For a retailer whose store is the brand, that is not a small thing.

Performance improves if you spend the freedom on performance. Serving a product page from pre-rendered markup, with price and stock filled in afterwards, is a genuinely better shape than assembling everything on request, and Largest Contentful Paint usually reflects it. But a headless build can also be slower than what it replaced. A storefront that ships a heavy client bundle and calls four services before anything is readable is a downgrade with a nicer diagram.

The multi-surface argument holds only when you genuinely have multiple surfaces. One website is a weak reason to decouple. A website, an app, a wholesale portal and a partner feed is a strong one. Search visibility, meanwhile, neither improves nor degrades by architecture alone: it depends on whether crawlers receive a complete page, which is ordinary e-commerce SEO work in either architecture.

Checkout is where the work is

Checkout is the part teams underestimate, and it is not close.

On a mature platform, checkout is the most heavily tested code in the building. It handles tax by jurisdiction, shipping rules, discount stacking, gift cards, partial refunds, address validation, fraud screening, the individual quirks of each payment method, and retry behaviour when a provider times out mid-transaction. All of it inside a compliance scope somebody else defined and keeps current.

Rebuilding that is possible. Rebuilding it well is a project in its own right, and rebuilding it while launching a new storefront is two projects sharing one deadline and one team. The answer we recommend most often is unglamorous: keep the platform’s hosted checkout and decouple everything in front of it, accepting a hand-off that is slightly less elegant in exchange for never owning a payment edge case at midnight.

Whichever way you go, checkout is where you find out whether you have monitoring. A payment provider failing on a monolith is the vendor’s incident and the vendor’s status page. On a decoupled build it is yours, and you need to know before a customer tells you, which is the case made in observability for a site that only breaks occasionally.

Search and promotions stop being free

Search becomes a product you own

On a monolith, search is a box. It works acceptably, handles misspellings badly, and belongs to nobody. Decoupled, search becomes a service you select, a schema you design, an index you keep in sync, and a relevance problem somebody has to tune while looking at real queries.

That is often a genuine improvement, because platform search tends to be the weakest thing in the store and merchandisers know it. The improvement is not automatic, though. An index that drifts out of step with stock shows products that cannot be bought, and there is no vendor to escalate that to on the afternoon before a sale.

Promotions are not a field on a product

Promotions are the harder case, because they look simple and are not. Buy two get one free, on one category, excluding items already reduced, stacking with a customer-group discount but not with a code, capped per order, in one currency and not the other: that is a rules engine. Monolithic platforms ship one, with an interface a marketer can drive without asking anybody for a deployment.

Decoupled, those rules resolve wherever you decided they resolve, and the marketer’s preview usually resolves nowhere at all. This is the point where a team learns that the campaign calendar assumed a capability nobody costed. If your promotions are simple and stable, that is survivable. If promotions are how you actually sell, protect them: keep the rules inside the engine that has a working editor, and let the storefront ask what the price is rather than compute it.

The integration surface you inherit

A monolith is one vendor relationship. A composable build is several, and every join between them belongs to you.

• Version drift. Four services deprecate on four schedules. Somebody has to read four changelogs, and that somebody is rarely named in the plan.
• Data that has to agree. Product identifiers, stock, price and tax must mean the same thing in every service. Wherever they disagree, the storefront tells a shopper something untrue.
• Failure that is now partial. A monolith is up or down. A composable store can have working browse, broken search and a cart that accepts an item it cannot price.
• Environments multiplied. Staging is only real if every service has a staging tier and somebody keeps them all seeded with data that resembles production.
• Contracts and renewals. Each vendor has a plan, an export, a rate limit and a price that moves. The cost of leaving is the sum of them, not the largest one.

None of this is exotic. It is the ordinary cost of software you did not write, set out in the dependency you shipped but did not write, multiplied by the number of boxes in the diagram. Each service also carries a permanent cost after launch, which is the argument in the standing cost of every feature you ship.

The infrastructure underneath is the least reversible part of the exercise. Where the storefront renders, where the cache sits, and which region the engine runs in are hosting decisions that are hard to reverse once real orders are flowing through them.

A readiness test worth failing

We run a short test before anybody draws an architecture. Six questions, answered out loud, with the people who will still be here next year. A weak answer in the first four is a strong signal to stay where you are for now.

1. Do you have a front-end team, not a front-end contractor? Headless converts a theme into an application, and applications need somebody who owns them after launch, not only up to it.
2. Can you name the capability the platform cannot express? One sentence, specific. If the honest answer is that the theme is annoying, you want a redesign, not a replatform.
3. Is there more than one surface consuming the catalogue? Not a possible app someday. Committed, with a date and a budget behind it, or it does not count as a reason.
4. Who owns search and promotions the month after launch? Name the person. If the name is the same developer who owns everything else, you have located the bottleneck early and cheaply.
5. What is the rollback? Decoupled launches resist reversal, because the old theme stops being maintained the day the new storefront ships.
6. What does the redirect map look like? Replatforming usually changes URLs, and the mapping is the artefact that decides whether the migration holds its traffic.

Run the test against the store you have rather than the one described in the meeting. That means assessing the current build honestly first, with findings kept separate from priorities, because "this is wrong" and "fix this before we replatform" are two different claims that get merged constantly. Assessment tooling such as Prooflin resolves findings, severities and recommendations into something a stakeholder will actually read, which matters here more than usual: this decision gets signed off by people who will not open a spreadsheet.

What transfers, capability by capability

The honest way to price a replatform is one capability at a time. The third column is your new backlog, and it does not shrink after launch.

The case for staying monolithic

We say this more often than the market does: for most stores the monolith is still the right answer, and choosing it is not a failure of ambition.

A single platform gives you a checkout somebody else tests, a promotions engine your marketer can drive unaided, search that is mediocre and present, upgrades applied by the vendor, and one support relationship on the day something breaks at the worst possible moment. Those are not consolation prizes. They are most of the work of running a store, done by somebody whose job it is.

The strategic version of the argument is worth reading beside this one: what a business sells is almost never its storefront architecture, a case our parent company makes in what a company actually sells. A shopper does not experience your rendering strategy. They experience whether the thing they wanted was in stock, priced correctly and easy to pay for.

The concession runs the other way too, and it is a real one. If the platform genuinely constrains how you sell, waiting does not make the migration cheaper. Catalogues grow, integrations accumulate, and the redirect map gets longer every quarter. A team that knows it will decouple eventually is better off fixing the content model and the URL structure now, so that the move becomes a front-end project later rather than an archaeological one.

Where we would start

If the readiness test passes, decouple in the order that keeps the store sellable throughout. Content and category pages first, because they carry the most traffic and the least risk. Product pages next, with price and stock fetched at request time so nothing goes stale inside a cache. Cart after that. Checkout last, and possibly never.

Do the boring artefacts before the interesting ones: the content model, the URL map, the redirect list, and a written definition of what a product actually is in your business. That is the part of an e-commerce build that decides whether the second year is calm, and it is the part everybody wants to skip because it produces nothing anyone can screenshot. Where the store is the business rather than one channel beside it, sequence the whole thing as a programme, which is the shape an e-commerce acceleration engagement is built around.

One condition flips the recommendation entirely. If the reason to go headless is that the platform cannot express how you sell, whether that is a subscription model it does not represent, business-to-business pricing it cannot hold, or a catalogue shape it argues with, then the constraint is real and delay only adds weight to the eventual migration. If the reason is that the site feels slow or looks dated, buy the fix for that and keep the checkout somebody else tests. Tell us what your platform will not let you do, and the answer usually settles itself inside one conversation.