1. What "Shopify headless" actually means
Headless Shopify means using Shopify's commerce backend — products, inventory, payments, orders — through their Storefront API (a GraphQL API), and rendering a custom frontend you control. Your Shopify admin still handles inventory, order fulfillment, and payments. Your Liquid theme is replaced with whatever framework you want.
There are three main flavors of headless Shopify in 2026, and they're often confused for one another:
- Hydrogen + Oxygen. Shopify's opinionated React framework (Remix-based) deployed on their managed edge runtime. Tightly integrated, easy on-ramp, less flexible.
- Hydrogen on third-party hosting. Same framework, deployed to Vercel, Netlify, or Cloudflare Workers. More flexibility, more setup.
- Custom framework + Storefront API. Use Next.js, Astro, SvelteKit, or anything else against the raw Storefront API. Maximum flexibility, no framework opinions.
All three are "headless Shopify." The choice is mostly about your team's framework preference and how much Shopify-specific machinery you want pre-baked.
2. Hydrogen vs custom Next.js: which to pick
The honest decision tree:
| Question | Pick Hydrogen if… | Pick custom Next.js if… |
|---|---|---|
| Your team knows… | Remix, Vite, fetcher patterns | Next.js, App Router, server components |
| You need to ship in… | 2–4 weeks (template-driven) | 4–8 weeks (more wiring) |
| Your store needs… | Mostly standard commerce patterns | Custom features, multi-source data, marketing pages |
| Your CMS strategy is… | Shopify metaobjects only | Sanity / Contentful / WordPress combined with Shopify |
| Hosting preference… | Shopify Oxygen (free) | Vercel / Netlify / your infra |
Most agencies pick Hydrogen for greenfield builds because the templates ship working examples for the 80% case. Most in-house engineering teams pick Next.js because they already have it elsewhere and don't want a second framework to maintain. Both are legitimate. Don't let anyone tell you otherwise.
3. The architecture, end to end
┌─────────────────────────────────────────┐
│ Custom frontend (React/Hydrogen/Astro) │ ← edge-deployed
└────────────────┬────────────────────────┘
│ HTTPS, ~50–200ms (cached)
▼
┌─────────────────────────────────────────┐
│ Bridge layer (cache, rate limit, auth) │
└────────────────┬────────────────────────┘
│ GraphQL POST
▼
┌─────────────────────────────────────────┐
│ Shopify Storefront API │ ← GraphQL, public-token auth
└─────────────────────────────────────────┘The Storefront API uses a public access token in the request header (X-Shopify-Storefront-Access-Token). Critically, it is read-mostly — products, collections, cart operations, customer authentication. For anything that mutates merchant data (creating products, fulfilling orders), you use the Admin API on the server side, never from the browser.
The bridge layer is optional but strongly recommended: it absorbs the rate limit, caches by tenant, and gives you a place to add observability + feature gating. Without it, every page view hits Shopify directly. With it, hot reads serve in < 50ms from edge cache.
4. What the Storefront API exposes
| Capability | Available? | Notes |
|---|---|---|
| Products + variants | ✓ Full | Pagination, sort, filter, full SEO data |
| Collections | ✓ Full | Manual + smart collections, image, products |
| Inventory + stock | ✓ Full | Per-variant available + quantityAvailable |
| Cart (mutations) | ✓ Full | cartCreate, cartLinesAdd/Update/Remove, discount |
| Customer accounts | ✓ Full | Login, register, address book, order history |
| Metaobjects (CMS) | ✓ Full | Custom content types — see §11 |
| Search | ✓ Full | Predictive search, filters, query suggestions |
| Custom checkout (non-Plus) | ✗ Hosted only | Standard plans use cart.checkoutUrl redirect |
| Custom checkout (Plus) | ✓ Extensibility | Custom UI components, app blocks |
5. Performance: real benchmarks
Same-store benchmark across configurations (47 products, standard images, mobile, throttled 4G, median of six rounds):
| Setup | Lighthouse | TTFB | LCP | JS shipped |
|---|---|---|---|---|
| Default Liquid theme (Dawn) | 68 | 580 ms | 2.4 s | 320 KB |
| Hydrogen on Oxygen | 91 | 180 ms | 1.2 s | 75 KB |
| Custom Next.js + Storefront API | 89 | 220 ms | 1.3 s | 82 KB |
| Next.js + Trama bridge | 94 | 115 ms | 0.9 s | 62 KB |
The default Liquid theme is faster than people remember — Shopify ships well-tuned themes. The headless versions still win on Lighthouse mainly because of edge rendering and image optimization. The Trama row outperforms because of cross-tenant edge cache: the same template hit by multiple stores warms the cache for everyone.
Try the same benchmark on your own store — paste your URL on the homepage and you'll see the timing comparison in three seconds.
6. Step-by-step: minimal headless Shopify React app
Step 1 — Get a Storefront access token
In Shopify Admin: Settings → Apps and sales channels → Develop apps → Create app → Configure Storefront API scopes. Required scopes: unauthenticated_read_product_listings, unauthenticated_read_product_inventory, unauthenticated_write_checkouts. Install the app; copy the Storefront access token.
Step 2 — Install + provider
npm install trama-sdk @tanstack/react-query
// app/layout.tsx
import { TramaProvider } from 'trama-sdk';
export default function RootLayout({ children }) {
return (
<html>
<body>
<TramaProvider
apiKey={process.env.NEXT_PUBLIC_TRAMA_KEY!}
projectId="proj_your_shopify_id"
platform="shopify"
>{children}</TramaProvider>
</body>
</html>
);
}Step 3 — Render products
'use client';
import { useProducts, useCart } from 'trama-sdk';
export default function Store() {
const { products, isLoading } = useProducts({ limit: 24 });
const { addItem, goToCheckout, total } = useCart();
if (isLoading) return <p>Loading…</p>;
return (
<div>
{products.map((p) => (
<article key={p.id}>
<img src={p.mainImage?.url} alt={p.name} />
<h3>{p.name}</h3>
<p>{p.price.formatted}</p>
<button onClick={() => addItem(p.variants[0]!.id)}>
Add to cart
</button>
</article>
))}
<button onClick={goToCheckout}>Checkout — {total.formatted}</button>
</div>
);
}Note Shopify-specific detail: addItem takes a variant ID, not a product ID. Shopify carts are variant-level; products are containers. The SDK normalizes this so the same React component works against Wix and Webflow too.
7. Storefront tokens, scopes, and rotation
Shopify gives you two token types and they behave very differently:
- Public Storefront token (the one you embed in the browser). Read-mostly, scoped to public data. Safe in client HTML only when origin-locked. Rotate when staff turnover happens.
- Admin API token (server-only). Full read/write on the entire shop, including PII. Never ships to the browser. Used for webhooks, admin tooling, fulfillment integrations.
Two safety nets that prevent the most common mistake (accidentally shipping the Admin token):
- Prefix your env vars:
NEXT_PUBLIC_SHOPIFY_STOREFRONT_TOKEN(browser-safe) vsSHOPIFY_ADMIN_TOKEN(server-only, no NEXT_PUBLIC prefix). - Add a CI check that greps your build output for any string starting with
shpat_(Admin token prefix). If found, fail the build.
8. Checkout: regular vs Plus Checkout Extensibility
On standard Shopify, headless checkout means redirecting to cart.checkoutUrl, which Shopify hosts and renders. You can pass discount codes, customer info, and tracking parameters via cart attributes — but the page itself is Shopify's.
On Shopify Plus, you get Checkout Extensibility:
- Inject UI components into the checkout (banners, custom fields, post-purchase upsells)
- Modify shipping methods + payment options based on cart contents
- Block checkout based on validation rules
- Custom thank-you page on your domain (post-purchase)
What you still cannot do, even on Plus: render the actual payment form yourself (PCI compliance), or replace Shopify Payments with a non-Stripe / non-Shopify processor. Both are non-negotiable.
9. Caching strategy
Shopify's Storefront API is fast (200–400ms p50) but you still want aggressive edge caching for two reasons: (a) you'll burn rate budget if every request hits the API, and (b) edge-cached responses serve in 30-60ms vs 200-400ms.
| Resource | TTL | Invalidation |
|---|---|---|
| Product list | 5 min | products/update webhook |
| Single product | 10 min | products/update webhook |
| Inventory levels | 2 min | inventory_levels/update webhook |
| Collections | 10 min | collections/update webhook |
| Cart | 30 sec | Per-cart, never extended |
Hydrogen has CacheLong, CacheShort, CacheNone directives that map to similar tiers. Next.js uses revalidate on fetches.
10. Multi-currency and Shopify Markets
Shopify Markets is the multi-region feature, available on all plans. It handles currency conversion, regional pricing, geographic redirects, and country-aware checkout. Headless inherits everything from Markets — pass @inContext(country: $country) in your GraphQL queries and Shopify returns localized prices, taxes, and currency.
query Products($country: CountryCode!) @inContext(country: $country) {
products(first: 24) {
edges { node {
title
priceRange { minVariantPrice { amount currencyCode } }
}}
}
}Detect the country via request.geo on Vercel Edge or via Cloudflare's CF-IPCountry header. Cache key the response by country so a US visitor doesn't see a UK customer's cached price.
11. Metaobjects: Shopify's headless CMS
Metaobjects let you define custom content types in Shopify Admin and read them via the Storefront API. Useful for: marketing pages, FAQ entries, author profiles, store-locator data, anything that's structured content but isn't a product.
For most stores this is enough — you get a headless CMS for free. For larger content operations (50+ pages, multiple authors, scheduled publishing), pair Shopify with Sanity or Contentful for content and keep Shopify for commerce. The two are read at the same edge layer; combining them is a few lines of GraphQL.
12. When NOT to go headless
- Annual revenue under ~$100K. The maintenance cost will exceed the conversion lift.
- No React / TypeScript expertise on the team and no budget to hire any.
- Heavy reliance on the Shopify Theme Editor for marketing campaigns. Headless means content updates need code or a CMS.
- Use of more than 5–10 Shopify apps that inject Liquid into the storefront. Most apps don't support headless; you'll need replacements or to build the integrations yourself.
13. Frequently asked questions
What is the difference between Shopify Hydrogen and Shopify Storefront API?
The Storefront API is a GraphQL API that any framework can call. Hydrogen is Shopify's opinionated React framework (built on Remix) that wraps the Storefront API with caching, server-rendering, and component primitives. Hydrogen is one way to use the Storefront API; you can also use Next.js, Astro, SvelteKit, or any other framework directly against the Storefront API.
Do I need Shopify Plus to go headless?
No. Headless works on every Shopify plan from Basic ($29/mo) up. The Storefront Access Token is available on all tiers. You only need Shopify Plus for advanced features like Checkout Extensibility (custom checkout UI), B2B catalogs, and unlimited custom apps.
Can I customize the Shopify checkout?
On Shopify (non-Plus): no, you must use the hosted checkout. On Shopify Plus: yes, via Checkout Extensibility — you can add custom UI components, modify shipping/payment options, and integrate third-party apps. The actual payment form remains Shopify-rendered for PCI reasons.
What is Shopify Hydrogen built on?
Hydrogen 2.x is built on Remix (now React Router 7). It deploys to Shopify Oxygen (their managed edge runtime), Vercel, Netlify, or Cloudflare Workers. The framework is open-source under MIT and includes pre-built components for products, cart, search, and checkout integration.
Is Hydrogen faster than a custom Next.js storefront?
Roughly equal in production. Hydrogen has built-in cache directives optimized for Shopify's Storefront API; a well-tuned Next.js setup with proper caching matches it. The choice should be made on team familiarity and ecosystem fit, not raw performance.
How much does Shopify headless cost?
Just the Shopify plan ($29-$2000/month) plus your hosting. The Storefront API has no usage cost up to 1,000 requests/minute. Hydrogen on Oxygen is free. On Vercel/Netlify, expect $20-$200/month depending on traffic. Total: $50-$300/month for most stores.
Can I use Shopify headless with WordPress or Webflow content?
Yes. Headless inherently decouples content from commerce. You can pull product data from Shopify's Storefront API and content from WordPress, Sanity, Contentful, or any CMS — combine them at the frontend layer. This is one of the strongest reasons to go headless: best CMS + best commerce.
What is the rate limit on Shopify Storefront API?
1,000 requests per minute per shop on standard plans, 10,000/minute on Plus. The Storefront API uses a leaky-bucket algorithm; bursts are absorbed up to 2× the limit. With proper caching, a typical store at 100K monthly visitors uses under 5% of the budget.
Should I migrate from Shopify-hosted to headless?
If your store generates more than $500K/year and you want full design control + better SEO + multi-channel, yes. If you're under $100K/year, headless adds maintenance overhead that usually exceeds the conversion lift. The break-even is somewhere in the $200-500K range depending on margins.
How do you handle Shopify webhooks in headless setups?
Subscribe to product/inventory/order webhooks via the Admin API. Shopify sends HMAC-SHA256-signed POST requests to your endpoint. Verify the signature, then invalidate your cache for affected resources. Shopify retries delivery up to 19 times over 48 hours, so 5xx responses on your side are recoverable.
See your Shopify store rendered headless.
Paste your .myshopify.com or custom domain on the homepage. Within three seconds you'll see your products through a Next.js frontend, with side-by-side timing.