Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 55 ยท Storefront API and Headless

Headless Commerce and Hydrogen

Understand headless commerce on Shopify: when it pays off, what Hydrogen and Oxygen provide, the real trade-offs, and a runnable storefront fetch layer with mock data.

A normal Shopify store is coupled: the theme (Liquid templates) renders the pages, Shopify hosts them, and the checkout is one click away. Headless commerce cuts that link. The "head" (the storefront the shopper sees) becomes your own application, written in any framework and hosted anywhere, and it talks to Shopify's "body" (products, carts, checkout) through the Storefront API you have just met.

Headless is one of the most over-sold ideas in e-commerce. It can be the right call, and it can also double your costs for no visible gain. This lesson explains what you get, what you give up, what Shopify's own headless tools (Hydrogen and Oxygen) are, and how to decide. The Shopify-specific commands are read-only; the runnable part is a tiny fetch layer with mock data that shows the architecture's central habit: the page never talks to the API directly, it talks to a small data layer. The theory of platform choices is in Choosing a Platform and Architecture and Scaling.

What changes when you go headless

In a theme-based store, Shopify gives you, for free: product, collection and cart pages, SEO tags, a sitemap, theme editor customization for non-developers, apps that add blocks with theme app extensions, analytics hooks and caching on Shopify's edge. In a headless build, every one of those becomes your responsibility, or you rebuild it:

  • Routing, page templates and meta tags.
  • Caching and performance. Fast headless sites are fast because of careful caching, not because they are headless.
  • The sitemap, redirects, structured data and canonical URLs (E-commerce SEO).
  • Support for merchant tools: the theme editor does not edit your custom app, so content changes need a CMS or code.
  • Apps. Many apps inject into themes. A headless storefront does not run them; the app must offer a Storefront API integration, or you rebuild that feature.

What stays with Shopify even in a headless setup: the catalog, inventory, customers, discounts, the checkout (reached by the cart's checkoutUrl, see Building a Cart with the Storefront API), payments, taxes, orders and fulfillment. You are replacing the presentation layer, not the commerce engine.

When headless is worth it

Good reasons:

  • A truly custom experience that Liquid cannot give you: a configurator, an interactive 3D product viewer, heavy personalization, an app-like feel.
  • Many channels from one backend: the same catalog in a website, a mobile app, in-store screens and a content-rich editorial site.
  • An existing front-end team and platform that must be reused, with design systems and tooling already in place.
  • Content-led commerce, where a CMS drives page layout and Shopify only supplies products and cart.

Weak reasons: "it is modern", "it will be faster" (a lean theme is often faster than a heavy custom app), or "our designer wants a different look" (themes can be customized deeply). A short test: if you cannot name a specific thing the customer will get that a theme cannot provide, stay with a theme.

Theme storefront Headless storefront
Time to launch Fast Slower, a real software project
Running cost Included in Shopify plan Hosting, monitoring, developers
Design freedom High, within Liquid and sections Total
Apps Plug in Often need custom integration
Merchant self-service Theme editor Depends on what you build
Checkout Shopify Shopify (same)

Hydrogen and Oxygen

Shopify offers two products aimed at headless builds.

Hydrogen is Shopify's React-based framework for custom storefronts. It provides a project skeleton, data-loading patterns, helpers for the Storefront API (a client, cart handling, caching strategies, SEO helpers) and components. Recent versions are built on React Router, and the exact package names and scaffolding commands change between releases, so follow the current generator rather than copying an old tutorial. A new project starts from the CLI:

Terminal
# read-only: needs Node and a Shopify account
npm create @shopify/hydrogen@latest

Oxygen is Shopify's hosting for Hydrogen storefronts, running your server code on a global edge network and connected to your store through the Hydrogen channel for deployments. You can host a Hydrogen app elsewhere, and you can use the Storefront API with any other stack (Next.js, Remix, SvelteKit, a native mobile app) and any host. Hydrogen is a convenience, not a requirement.

Whatever framework you choose, a handful of habits repeat:

  1. Server-side data loading with a private token (Storefront API Basics) so the token never reaches the browser.
  2. Cache by data type. Product and collection data changes slowly and can be cached for minutes or longer; carts must never be shared between shoppers.
  3. Store only the cart ID in a cookie; the cart itself lives on Shopify.
  4. Forward the buyer's IP and country so pricing, taxes and abuse protection use the shopper, not your server.
  5. Handle failures gracefully: a failing API call should show a fallback or a cached page, not a blank screen.
flowchart LR
    B["Browser"] --> H["Your storefront<br/>(Hydrogen or other)"]
    H --> L["Data layer<br/>(cache + retries)"]
    L -->|"private token"| SF["Storefront API"]
    H -->|"checkoutUrl"| CO["Shopify checkout"]
    CMS["Optional CMS"] --> H

The storefront is yours; the catalog, cart and checkout remain Shopify's.

A tiny storefront data layer

The code below is not Hydrogen. It is a stand-in that shows the structure Hydrogen-style apps use: one function that fetches from the "API" (a mock here), a cache with a time-to-live so repeated page renders do not repeat the request, a stale fallback when the API fails, and a rule that carts are never cached. A counter shows how many real "API calls" were needed.

JS A cached fetch layer with stale fallback

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second example is the decision itself. It is a deliberately simple scorer: it counts reasons for and against going headless from a few yes/no answers. It cannot decide for you, but writing the criteria down makes the conversation with a client or team much clearer.

JS Score the headless decision

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Operating a headless store

Plan for the things a theme gave you silently. You need monitoring for your own server, a deploy pipeline, a plan for Storefront API version upgrades every quarter (API Versioning and Deprecations), a strategy for preview and staging, and an owner for SEO. If you also run a Shopify app, the webhooks it receives (product updates, for example) are the natural trigger to purge your storefront's caches.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In a headless Shopify setup, what does Shopify still provide?

    Headless replaces the presentation layer only. Products, carts, the hosted checkout, payments, taxes and orders remain on Shopify.
  2. 2. Which is the weakest reason to go headless?

    A lean theme can outperform a heavy custom app. Speed comes from careful engineering and caching, not from the architecture label.
  3. 3. What is Oxygen?

    Oxygen is Shopify's edge hosting for Hydrogen. You may host a Hydrogen app elsewhere, and Hydrogen is optional for using the Storefront API.
  4. 4. Which data should never be shared between shoppers by a cache?

    A cart belongs to one shopper. Product and collection data can be cached; carts and personalized data must not be.
  5. 5. Why should a headless server forward the buyer IP?

    Requests with a private token come from your server, so you pass the shopper's address along in a header.

Summary

  • Headless means a custom storefront on the Storefront API; Shopify still runs catalog, cart, checkout and orders.
  • It pays off for custom experiences, multi-channel use and existing front-end teams, and costs more in time, hosting and maintenance.
  • Hydrogen is Shopify's React framework for headless storefronts and Oxygen its hosting; neither is required.
  • Good habits: server-side loading with a private token, caching by data type, carts never shared, graceful failures.

Next: Webhooks in Shopify.