Progressive headless: the Storefront API inside a Liquid theme

Headless is usually presented as a binary: a Liquid theme, or a separate React application. There's a third option that most stores that "use the Storefront API" are actually doing, and almost nobody quotes for it.

Keep the storefront in Liquid. Build one or two specific pieces against the Storefront API inside it.

What this looks like

The theme renders everything — homepage, collections, product pages, blog, account — server-side, with Shopify handling SEO, the theme editor and app compatibility exactly as normal.

Then one component is API-driven:

• A fast custom cart that updates without a page load and can do things the theme's cart can't.
• Live search with instant results and filtering.
• A product configurator with dependent options and calculated pricing.
• A quick-add or quick-view that fetches variant data on demand.
• A bundle builder — build your own bundle.
• A store locator or availability checker pulling live inventory.

What you keep

This is the argument, and it's a strong one:

• The theme editor. Merchandisers still rearrange pages and run campaigns without a developer. This is the cost of full headless that hurts most.
• App compatibility. Apps that inject into Liquid themes still work.
• Shopify's SEO handling — canonicals, sitemaps, redirects, hreflang, structured data. All the work full headless makes yours stays Shopify's.
• Server-side rendering for everything that matters to search engines.
• A far smaller codebase to maintain.

What you get

• API-driven interactivity exactly where the theme is limiting.
• Speed on the interaction that matters, without rewriting the pages that were already fine.
• A much smaller budget — mid four figures rather than five, and weeks rather than months. What headless costs.

How it works technically

The Storefront API is designed for browser use: its tokens are public and scoped to what's safe to expose. So your theme can query it directly with JavaScript.

Practically:

1. Create a Storefront API access token with the scopes the feature needs.
2. In the theme, write a small module that queries the API.
3. Render the results into the page.
4. For cart operations, use the Cart API and hand off to Shopify's checkout with the checkoutUrl — the Cart API.

No separate application, no separate hosting, no separate deploy pipeline.

Where to be careful

• Keep the bundle small. The point is a faster interaction. Shipping 200KB of JavaScript for a search box defeats it — JavaScript performance.
• Don't duplicate cart state. One source of truth. Two carts disagreeing is a bug customers report and you can't reproduce.
• Render something server-side. An API-driven component that's empty until JavaScript runs is invisible to crawlers. If the content matters for SEO, render it in Liquid and enhance it.
• Handle failure. The API can be slow or unavailable. The component must degrade to something usable.
• Public tokens are public. Don't try to do anything privileged with them; that's the Admin API's job, server-side — the API map.

When to go further

Progressive stops being enough when:

• Most of the storefront needs this treatment, not one part.
• You need a front end the theme architecture genuinely fights.
• You're composing several data sources across the whole site.
• You need multiple front ends on one backend.

At that point the codebase you've grown inside the theme is a liability, and a proper Hydrogen or Next.js build is the honest answer.

But you'll have arrived there knowing exactly what you need, having paid a fraction of the cost to find out.

The choice isn't theme or headless. It's how much of the storefront needs to be headless — and for most stores the answer is one component, not all of them.