An Opinionated Guide to Shopify Headless

‍
Part 2: The Build, the Migration and the Project Plan

Reading Time (min) : 15
Author Name : Umar Farooq

In Part 1 we did the hardest work, which was deciding whether to go at all. If you are here, you walked the Four-Wall Test and at least one wall is real. You can name it, you can quantify what it is costing you and you can point to the lever you expect to move.

Good. Now we build. And the build is where most of the regret actually gets manufactured. Not in the decision, but in the dozen quiet choices that come after it.

I am going to hand you this the way I would hand it to a product team I trust. Lead with the decision, name the trade-off, lay out a sequence you can run. No theory walls. Let us go.

‍

Part 5: The Architecture and Why “Which Framework” Is the Wrong First Question

Everyone wants to open with the question of Hydrogen or Next.js. That is the second question. The first one is the question that actually decides it. How committed are you to staying on Shopify, and how heavy is your non-commerce content? Answer those two honestly and the framework largely chooses itself.

Here is the real decision matrix as it stands in 2026.
‍

Table 2: The headless architecture decision

For most merchants who have genuinely earned the build, the honest default in 2026 is Hydrogen on Oxygen. It has been generally available since 2023, it now runs on React Router v7, which is the evolution of Remix, with Vite as its build tool, and it is in production at brands like Allbirds and Gymshark. This is no longer early-adopter technology. It cuts weeks off the timeline and lowers long-term maintenance precisely because it stops fighting the platform.

Here is the reframe that matters most, because it inverts the old instinct. On Shopify in 2026 the coupling is the feature, not the compromise. Shopify has spent the last year making tight integration worth more rather than less. There is schema-aware tooling that wires Cursor, Claude Code and VS Code directly into Shopify’s APIs with live validation, along with bot-auth perimeters and variant-level publishing. Trying to recreate all of that on a fully decoupled custom backend means spending sprints rebuilding what Hydrogen hands you in a plate. If you wanted React control inside Shopify’s graph, Hydrogen is the answer. If you wanted to escape Shopify’s graph entirely, go back and re-read Part 1.

My architect’s heuristic, the same one I apply to any system: start coupled and pragmatic. You can always add complexity when you feel the seams. You can almost never remove it once it has become load-bearing.

‍

Part 6: The Stack You Are Actually Signing Up For

“Headless Shopify” is a small set of pieces. Know each one before you scope, because each is a line item and a point of failure.

The Storefront API, which is GraphQL, is your read layer for products, collections and content. It is where your storefront gets its data. The Storefront Cart API is where you create and manage carts, after which you send the shopper to checkout using the cart’s checkout URL. This is what replaced the old, now-dead Checkout API. The Customer Account API handles login, order history and account management for the signed-in shopper. Checkout Extensibility together with Shopify Functions is how you customize the hosted checkout, covering upsells, custom fields, discount and shipping logic, without touching its core. Functions is where your custom discount, shipping and bundle logic now lives. And Oxygen is Shopify’s edge hosting for Hydrogen, deployed straight from your repo and included with paid plans, so there is no separate hosting contract to negotiate.

Internalize one mental shift and half the downstream decisions get easier. You are not building a store. You are building a frontend application that consumes commerce services. That changes how you staff it, how you test it and how you ship it, which is the rest of this guide.

‍

Part 7: The CMS You Cannot Skip

I will say this as plainly as I can, because it is the single most common headless post-mortem I come across. A headless store without a CMS means every content change is a developer deployment.

Picture the day-to-day. Your merchandiser wants to launch a collection, swap a hero banner or push a seasonal landing page. On Liquid they do it themselves in minutes. On a headless store with no content layer they open a ticket, wait for a developer and wait for a deploy. Marketing velocity collapses, with agencies reporting drops of 60 to 80 percent, and the resentment shows up in team meetings. You will have spent six figures to make your marketing team slower. I have watched this exact thing sour a launch that was, technically, a complete success.

So the CMS is not optional. It is part of the build, and it is the line item proposals love to quietly forget. The real options come down to a handful.

• Sanity is developer-loved, flexible and cheap to start, though it needs developers to model the content.
• Contentful is enterprise-grade, usage-priced and scales to serious complexity.
• Storyblok offers visual component editing your marketers can actually use.
• Hydrogen-native visual editors such as Weaverse are built so merchandisers can edit without a developer, collapsing the CMS and the page-builder into one.

The choice hinges on a single question. Who edits content, and how often? If marketing ships daily, prioritize a visual editor a non-technical person can drive. If content is rare and structured, a developer-centric CMS is fine. Get this wrong and the architecture works perfectly while the business quietly seizes up.

Part 8: The SEO Migration, the Highest-Risk Thing You Will Do

Here is where good headless builds actually die. Not in the architecture, but in the migration. You are replacing every URL on a site that Google already trusts. Do it carelessly and you do not get a faster store. You get a faster store that nobody can find.

The non-negotiables, in priority order, are these.

First, the redirect map is the highest-risk item in the entire project. Every URL on the old site needs a tested 301 to its new equivalent. Build and test that map before launch, not during it. This is the most common SEO failure point in any migration, headless or otherwise.

Second, server-side rendering is mandatory. Both Hydrogen and Next.js do SSR, and search engines must receive fully rendered HTML. Shipping a client-side-only storefront in 2026 is malpractice, and no competent team does it.

Third, structured data is now your job. Native Shopify themes generate product and collection JSON-LD automatically. Headless does not, so you build it yourself. It is straightforward and it must not be skipped. In an agentic-discovery world, which we are about to get to, structured data is not just SEO hygiene. It is how machines read your catalog.

Fourth, Core Web Vitals are a ranking factor. The performance ceiling you paid for is also an SEO lever, but only if you actually reach it.

Treat the migration as its own project, with its own owner, its own checklist and its own go or no-go gate. It is not a launch-week task.

‍

Part 9: The Compliance Clock, the Deadlines That Break Stores Quietly

This is the part nobody puts on the romantic headless slide, and it is the part that pages you at 3 a.m. Shopify has been re-platforming its checkout layer, and the deadlines are real, sequential and dangerously easy to confuse. Confusing them is the most expensive planning mistake a Plus store can make right now

Start with checkout.liquid, which is deprecated. Information, shipping and payment pages had to move to Checkout Extensibility by 13 August 2024. Thank-you and order-status pages had to move by 28 August 2025 for Plus, with non-Plus running through 26 August 2026. Shopify has been auto-upgrading stores that did not move, which means lingering custom checkout code and Additional Scripts simply stop rendering. The most insidious symptom is that your post-purchase pixels and analytics break quietly, and it looks like underperforming ads until someone finally digs into the data.

Then there is the separate track of Shopify Scripts moving to Shopify Functions. This one has its own deadline. Scripts are discontinued on 30 June 2026. If your store uses Scripts for discount combinations, tiered shipping, B2B pricing or bundle logic, that logic stops working on 1 July 2026. The migration path is Functions, written in JavaScript or Rust. If you have not started, this is very likely your most urgent open item as you read this.

Behind all of it sits PCI DSS v4, which is a large part of why this is happening at all. The old raw-script-injection model could not meet modern payment-security standards. The hosted, extensibility-based model is the compliant path, which is one more reason you do not want to own checkout.

For a headless build specifically, your architecture must assume Shopify-hosted checkout via the checkout URL, with Checkout Extensibility and Functions for any customization. Any plan that quietly leans on legacy checkout customization is already broken. Audit this on day one of scoping, not in QA.

Part 10: The Team and Operating Model, the Cost Nobody Scopes

A headless storefront is a living application. It needs an owner with a pulse, not a launch and a handshake.

The blunt truth from the post-mortems is that a Hydrogen store without a full-time senior React engineer, or a committed agency retainer, becomes a liability. Updates stall, features that took weeks start taking quarters, the backlog grows and the store you built for agility becomes the slowest thing you own [3]. Before you start, force a real answer to three questions.

1. Who ships? Name the engineering capacity, whether that is in-house senior React talent or a retained studio. “We will figure it out” is not an answer.
2. Who merchandises? This is the CMS decision from Part 7 made concrete. Which humans edit what, without a deploy.
3. Who owns the redirect map, the structured data, the Core Web Vitals and the compliance deadlines? These are nobody’s job until they become an incident. Assign them now, by name.

This is also where the real cost lives. The build is the visible number. Ownership is the recurring one. Headless converts a slice of your platform spend into a permanent engineering spend. If that trade does not have a revenue lever behind it, you did not have a wall. You had a wish. I keep sending you back to Part 1 because that is where the discipline lives.

Part 11: Build for Agentic Discovery, the 2026 Reason This Changed

I flagged this as a wall in Part 1. Here is the implementation reality, because it is quietly the most strategic part of the whole exercise.

The frontier of discovery is moving. Shopify now lets Hydrogen storefronts plug into the Storefront MCP, which means building AI shopping agents directly into your store that can recommend products, fill carts and guide shoppers using live product and customer data. Separately, Shopify Catalog is making products discoverable inside AI assistants such as ChatGPT and Perplexity, opening a channel that did not exist two years ago.

What that means for the build comes down to three things. Structured, API-first data stops being hygiene and becomes distribution. The same clean JSON-LD and Storefront API discipline that helps SEO is what lets a machine read, recommend and transact your catalog, and headless architectures are structurally better at this than bolted-together Liquid stores. Speed becomes a discovery factor and not just a UX one, because agentic traffic punishes slow, messy stores harder than humans do. A bot does not wait politely. And you should design the data layer for non-human readers now, treating the question of whether an AI agent can understand and act on your storefront as a first-class requirement rather than a phase-two nice-to-have.

This is the one place I will let myself sound like a futurist. The merchants building clean, structured, headless storefronts today are not just buying a faster site. They are buying a readable one, readable by the AI intermediaries that will increasingly stand between your products and your customers. That is a genuine reason to go headless, and it simply did not carry weight in 2023.

‍

Part 12: The Phased Plan, How to Run This Without a Big-Bang Disaster

If there is one tactical thing to take from this guide, it is this. Do not big-bang a headless migration. The smartest approach is incremental. Replace the highest-value surface first, prove it and then expand. Keep checkout untouched the entire time.

Phase 0 is to earn it and prove the cheap fix is exhausted. Run the clean Liquid speed pass. Audit apps, images and scripts. Confirm the wall is real and the gain is not just hygiene. Get written alignment between marketing, engineering and leadership on the wall, the cost and the lever. The exit criterion is a one-page decision record everyone signed.

Phase 1 is to decide and de-risk. Lock three things: the architecture (with Hydrogen and Oxygen as the default), the CMS (chosen by who-edits-what) and the hosting. Audit the compliance clock and the Scripts-to-Functions migration. Build the redirect map and the SSR and structured-data plan as deliverables, not as intentions. The exit criterion is a redirect map drafted and tested in staging, with every compliance item assigned an owner and a date.

Phase 2 is to ship one surface. Pick the surface where the wall hurts most. That is often the product and collection pages for an experience wall, or a high-traffic landing surface for a performance wall. Build it headless, wire it to the Storefront API, keep everything else on Liquid and keep checkout on Shopify. The exit criterion is that the new surface beats the old one on the metric you named, which is conversion, not Lighthouse.

Phase 3 is to expand deliberately. Migrate the next surfaces only as each one proves out. Maintain the redirect map and the structured data continuously. Bring merchandisers onto the CMS and confirm they can ship without you. The exit criterion is that marketing velocity is at or above where it was before the migration.

Phase 4 is to build forward. Now you invest in the things that justified the architecture in the first place: the configurator, the agentic-discovery readiness, the multi-surface composability. This is where the ceiling you paid for finally turns into revenue.

‍

Part 13: The Pitfalls, and How to Avoid Them

I have seen the same mistakes repeat across enough builds to name them. Here they are in the problem-and-solution form, so you can catch yourself before they cost you.

Pitfall 1 is going headless for a problem a speed pass would have solved.

• Problem: six figures spent to fix slow pages that were slow because of app bloat and unoptimized images.
• Solution: Phase 0 is non-negotiable. Exhaust the cheap fix and measure before you commit.

Pitfall 2 is forgetting the CMS.

• Problem: every content change becomes a deploy, and marketing velocity craters.
• Solution: scope the CMS as part of the build, chosen by who-edits-what.

Pitfall 3 is treating the migration as a launch-week task.

• Problem: no redirect map, lost rankings, traffic falling off a cliff after launch.
• Solution: the migration is its own project with its own owner and go or no-go gate. Redirect map first.

Pitfall 4 is confusing the two compliance deadlines.

• Problem: the team migrates checkout.liquid and assumes Scripts are handled too, then discount logic breaks on 1 July 2026.
• Solution: track Checkout Extensibility and Scripts-to-Functions as two separate workstreams with two separate dates.

Pitfall 5 is launching without a named owner.

• Problem: the store ships, the agency rolls off and there is no senior engineer to maintain it.
• Solution: confirm ongoing ownership before you start. No owner, no build.

Pitfall 6 is measuring the wrong thing.

• Problem: the team celebrates a green Lighthouse score while conversion stays flat.
• Solution: define the success metric in business terms up front and hold the build to it.

Part 14: Measuring Success, What Good Actually Looks Like

You cannot improve what you do not measure, and “the site feels faster” is not measurement. Hold the build to numbers, in three layers.

Table 3: The headless success dashboard

If the lagging numbers do not move, the build did not earn its cost, and you need to know that early rather than at the next budget review. Track all three from launch.

‍

Part 15: The One-Page Go or No-Go You Should Fill in Before You Spend Anything

Steal this. It is the decision record I would require before approving a headless build, modeled on a simple Architecture Decision Record, the same discipline I use for any consequential technical choice.

Decision: go headless on Hydrogen and Oxygen, Next.js or other. Yes or no.

The wall: which of the four walls (Experience, Performance, Composability, Discovery) blocks us? Name it in one sentence.

The cost of the wall: what is it costing us today, in money or velocity? If we cannot quantify it, we have not hit it.

The lever: what specific metric do we expect to move, and by roughly how much?

The cheap fix: have we exhausted the Liquid speed pass and CRO first? What is the evidence?

Ownership: who ships code? Who merchandises without a deploy? Who owns redirects, structured data, Core Web Vitals and the compliance deadlines?

The budget, honestly: build, plus ongoing engineering, plus Shopify Plus, plus the CMS, plus integration. Does the lever clear it inside 24 to 36 months?

The compliance clock: are we clear of legacy checkout.liquid, and is our Scripts-to-Functions migration done before 30 June 2026?

If you can fill that page in with confidence, you are no longer guessing. You are deciding. And that, far more than which framework you pick, is what separates the merchants who get a competitive advantage from the ones who get an expensive lesson.

‍

Conclusion: The Whole Guide in Three Sentences

Headless Shopify is not a faster website. It is a re-architecture you pay for with a problem you can name. The build is a set of quiet decisions, namely architecture, CMS, migration, compliance and ownership, and every one of them is where the regret or the advantage actually gets made.

Choose coupled and pragmatic, keep checkout on Shopify, ship incrementally and build for a world where machines read your store too. Do that, and headless stops being a promise you hope pays off. It becomes a lever you pull on purpose.

The market does not need more brands with beautiful headless storefronts they cannot maintain. It needs more merchants who went headless for a reason they could name.

Be one of them.

References

[1] Qualimero. “Shopify Hydrogen: The Complete Guide to Headless Commerce in 2026.” Hydrogen GA since 2023, React Router v7 and Vite, Allbirds and Gymshark in production.

[2] Weaverse. “Is Shopify Hydrogen Actually Headless in 2026?” The Shopify AI Toolkit wiring Cursor, Claude Code and VS Code into Shopify schemas, plus Web Bot Auth and variant-level publishing.

[3] COREPPC. “Shopify Headless with Hydrogen: When It Is Worth It.” The marketing-velocity drop without a CMS and the cost of building without a dedicated engineer.

[4] Shopify upgrade guidance and independent migration analyses on checkout.liquid (August 2024, August 2025, August 2026) and Shopify Scripts to Functions (30 June 2026), with PCI DSS v4 as the underlying driver.

[5] Ask Phill. “Shopify Headless Commerce: When It Is Worth It and What It Costs.” Redirect maps as the highest-risk migration item, plus SSR and structured-data requirements.

[6] Shopify. “Hydrogen Update, Winter ’26 Edition.” Storefront MCP and Shopify Catalog discoverability in AI assistants. hydrogen.shopify.dev.
‍

This guide is based on my own experience building Shopify apps and e-commerce storefronts at Alchemative, and on what Shopify has shipped through the Winter ’26 edition. It is opinionated, practical and written for the leaders who have to live with the decision long after the launch. If you are scoping this for your own store, or sanity-checking a proposal that is already on your desk, start with the go or no-go page above.