Headless Commerce Architecture Explained

Introduction

Even once the idea of headless commerce makes sense, it's hard to make adoption decisions — or talk with developers — while the behind-the-scenes connections stay invisible. Get the overall picture first, and the individual technical terms become much easier to place.

This article explains the architecture of a headless EC site built with Shopify and Next.js, in three steps: how the two APIs divide the work, how data flows, and what to weigh before adopting. We'll stay away from code and stick to the structural story — what connects to what.

Two APIs, Two Roles

Shopify offers two APIs (service windows where systems exchange data) with distinct roles, and this division is the foundation of any headless build.

Storefront API — the Window for Users

This API serves the actions users take on the website: fetching products and collections (categories), adding to cart, starting checkout, and member login. Data requests use GraphQL (a query format that asks for exactly the data you need in one round trip).

Its access token (a string that works like a permission pass) is designed to be safely public, so it can be called directly from the user's browser.

Admin API — the Window for Operators

This API handles operations that require operator privileges: updating inventory counts, managing orders, editing customer records, creating discount codes.

Its access token must stay secret and is never exposed to the browser. It is called only from the server side (Next.js's server-side processing).

Token Handling Is What Keeps It Safe

The difference between the two APIs is really a difference in who each window is open to. Mixing up the public token and the secret token would hand operator privileges to the outside world, so this one distinction is enforced at the architecture level, always. Put the other way around: respect this rule and a headless build inherits Shopify's security as-is.

Architecture Diagram

In one sentence: Shopify provides data through two service windows, and multiple screens — website, app, and more — use those windows to share the same data.

How Data Flows on the Way to a Purchase

Here's what happens behind the scenes in three moments, from finding a product to buying it.

Displaying the Product List

In one sentence: by the time the user arrives, the page already exists. It was built ahead of time using product data fetched from the Storefront API, so the user never waits.

Adding a Product to the Cart

Cart contents differ per person and change on the spot, so instead of pre-built pages, the API is called in real time. The division of labor: shared pages are prepared in advance, personal actions are asked about live.

Checkout

Payment happens on a page provided by Shopify, so card data never touches your own servers. The part with the heaviest security responsibility is left with the specialized service.

Balancing Freshness with Speed — and the Alternatives

ISR Keeps Pre-Built Pages Fresh

Prices and inventory change daily, but querying the API on every view would slow everything down. The answer is ISR (a mechanism that automatically rebuilds pre-built pages at an interval you set). Users get the fast pre-built page while contents refresh in the background. Product pages that change often get a short interval; a homepage that rarely changes gets a long one — tuned to each page's nature.

Hydrogen, the Official Option

Shopify also offers "Hydrogen," its official framework purpose-built for headless. Its integration with Shopify is tightly designed, making it a strong option for brand-new projects. If you have existing Next.js assets and know-how, building on the more widely adopted Next.js is the other path — the one this project took.

What to Confirm Before Adopting

Team and Budget

Owning your frontend means you need a team that can work with React/Next.js. Recently, having a non-engineer drive the build by instructing an AI agent (AI-powered development support) has become a realistic option as well. On cost, plan for Shopify's monthly fee plus hosting on Vercel (the place your built pages live) and development/maintenance labor. Timeline depends on scope, but one to two months is the minimum guide.

The Work That Operations Adds

You'll be maintaining both Shopify and Next.js, building a pipeline for shipping updates (deployment), and — when something breaks — figuring out which side the problem is on. More moving parts than theme-based operation is something to price in before you start.

Summary

The architecture of headless commerce clicks once you hold three points: two service windows (Storefront API and Admin API), the split between pre-built pages and real-time queries, and payments left entirely to Shopify. You gain speed and freedom; you take on more to manage. With both sides in view, starting from a small proof of concept is the recommended first step.