Most explanations of headless Shopify start with why you'd want it. I'd rather start with what it actually is, mechanically, because I think a lot of the confusion in this space comes from people deciding to go headless before they understand what's still Shopify and what isn't.
Short version: headless Shopify keeps Shopify running the back end, products, inventory, customers, and (almost always) checkout, while you build and host a custom front end that talks to that back end through APIs instead of Shopify's theme engine. The architecture isn't Shopify minus a front end. It's Shopify-plus-a-separate-system-you-now-own.
Here's how the pieces actually fit together.
The core split: what "headless" removes and what it doesn't
In a standard Shopify theme, one system does everything. Shopify renders the page (using Liquid), stores the data, runs the cart logic, and hosts checkout. There's no meaningful separation; you're working inside Shopify's own rendering layer the whole time.
The back end stays on Shopify: product catalog, inventory, customer accounts, order management, and checkout logic.
The front end is something you build separately, commonly with Shopify's own Hydrogen framework, or with Next.js, Nuxt, or another JavaScript framework and host yourself, or through Shopify's Oxygen hosting if you're using Hydrogen.
The key thing to understand is that "headless" refers to what happens to the front end, not a wholesale replacement of Shopify's commerce logic. You're not rebuilding checkout, inventory management, or payment processing from scratch. You're rebuilding the layer the shopper actually sees and clicks through. Headless Shopify development therefore requires planning beyond the storefront itself, particularly around APIs, frontend architecture, integrations, and ongoing maintenance.
The building blocks
A few components do the actual work, and mixing them up is where a lot of confusion starts.
Storefront API. This is the API your custom front end talks to. It exposes what a shopper-facing experience needs: products, collections, the cart, and customer account data through GraphQL. It's built for public, customer-facing use: authentication is lighter-weight than the admin side, and it's designed to be called from a browser or mobile app.
Admin API. This is a separate, more powerful API meant for merchant- and staff-facing tools, with access to order management, inventory adjustments, and shop configuration. It requires proper OAuth authentication and shouldn't be exposed to a customer-facing front end. Keeping these two APIs separate is a deliberate security boundary, not an arbitrary technical split.
Cart and checkout. Your custom front end builds and manages the cart through the Storefront API. When the shopper is ready to pay, the front end hands off to Shopify's checkout rather than collecting payment itself. That handoff matters: it lets you keep Shopify's PCI compliance, fraud protection, and payment infrastructure without having to reimplement any of it. Checkout customization in a headless setup is real but bounded: you're extending Shopify's checkout, not replacing it, and that's true even for larger merchants on more advanced plans.
Hydrogen and Oxygen. Hydrogen is Shopify's own React-based framework for building the custom front end, and Oxygen is Shopify's hosting layer for Hydrogen apps. Using both keeps your headless build inside Shopify's infrastructure. You're not required to use them; a Next.js front end hosted on Vercel that talks to the Storefront API is a legitimate headless architecture too, but Hydrogen and Oxygen are the path Shopify maintains and updates.
How a page request actually flows through the system
It helps to walk through what happens when a shopper loads a product page, because this is where the architecture stops being abstract.
The shopper's browser requests a page from your custom front end (hosted on Oxygen, Vercel, or wherever you've deployed it).
Your front-end code queries the Storefront API for the data that page needs: product details, pricing, images, and variant availability.
Shopify returns that data as structured JSON through GraphQL.
Your front end renders the page using its own components, styling, and layout logic completely independent of Liquid or Shopify's theme templates.
When the shopper adds something to their cart, your front end calls the Storefront API again to update the cart object.
At checkout, your front end redirects the shopper to Shopify's hosted checkout, passing the cart along so pricing, discounts, and line items carry over intact.
Shopify handles payment, fraud checks, tax, and order creation; then the order lands back in the same Shopify admin your team already uses.
Notice how much of this is still Shopify. You've taken over steps one, two, and four, fetching data and rendering it your way. In most implementations, everything downstream of "add to cart" still runs through Shopify's infrastructure.
Where content management fits in
One thing standard Shopify theme setups don't force you to think about: where non-product content lives. In a theme, Shopify handles that mostly through its own page and blog tools, plus metafields for structured extras.
In a headless setup, teams frequently pair Shopify with a separate content management system. Headless APIs let teams deliver content and functionality independently of the frontend, so a separate CMS can work alongside a commerce platform in a decoupled architecture. Contentful's guide to headless APIs explains that this separation lets APIs serve different frontend applications without being tied to a particular presentation layer.
Sanity and Contentful are common choices for content that isn't product data, such as landing pages, editorial, lookbooks, and brand storytelling. Your front end then pulls from two sources: the Storefront API for commerce data, and the CMS for content, and stitches both into the pages it renders. This isn't required; plenty of headless builds keep content in Shopify's metafields and skip a separate CMS entirely, but it's common enough that it's worth planning for explicitly rather than discovering the need mid-build.
The misunderstanding worth clearing up#
The most common misconception I run into is the assumption that headless means the entire experience, including checkout, becomes custom. It doesn't, in the overwhelming majority of implementations. Checkout stays on Shopify's hosted infrastructure because that's where PCI compliance, fraud protection, and payment processing already live, and rebuilding it yourself would mean taking on liability most merchants have no interest in assuming.
If a pitch for a headless build implies you'll have full custom control over checkout itself, double-check what your specific plan actually permits, rather than assuming it by default.
What this means practically for a team building it
Understanding the architecture changes what you should be asking a development team or agency before committing:
Which front-end framework are they proposing, and does that match the skills your team can maintain afterward? A headless implementation requires developers comfortable with frontend, backend, and APIs. Full-stack developer responsibilities cover many of these cross-functional skills.
Are they using Hydrogen/Oxygen or a separate stack like Next.js on their own hosting, and who owns that hosting relationship?
How is checkout being handed off, and what happens to cart data, discounts, and customer identity across that handoff?
Is a separate CMS part of the plan, and if so, who will maintain the content structure long-term?
What's the plan for keeping the front end in sync with Shopify's API changes over time?
These are architecture questions, not vendor-pitch questions, and they're a reasonable thing to ask regardless of who's building it.
Bottom line
Headless Shopify architecture is a front-end swap connected back to Shopify's existing commerce engine through the Storefront API, with checkout still running through Shopify's own infrastructure in nearly every real-world implementation. Once you see it as "keep the engine, replace the dashboard" rather than "rebuild the car," the rest of the decisions which framework, whether to add a separate CMS, how much engineering capacity you actually need get a lot easier to reason about.
Top comments (0)