Headless Magento Architecture: APIs, Front-ends and Data Sync

This is a technical guide to headless Magento architecture for developers and technical leads: which parts a headless Magento 2 store has, how the storefront gets its data, what happens to the cart, checkout, extensions and SEO, and what to check before you start. For the business side (benefits, costs, when it's worth it) see What is headless Magento.

The parts of a headless Magento store

A headless Magento 2 store usually has five layers:

1. Magento back end: catalogue, prices, stock, customers, cart, checkout, orders and admin.
2. APIs: Magento's GraphQL and REST APIs.
3. Storefront: a JavaScript application that renders the pages, on its own server.
4. Catalogue and search index (optional, but common): serves categories, filters and search outside Magento.
5. CDN and cache: caches pages and assets, protects the store, and routes traffic.

Content such as blog posts, banners and landing pages often lives in a separate headless CMS.

GraphQL or REST?

Magento 2 has both:

• GraphQL is built for storefronts. It covers products, categories, CMS content, customer accounts, the cart and checkout, and returns only the fields you ask for. Magento can cache GraphQL GET requests in Varnish.
• REST covers almost everything in the admin and is the usual choice for integrations with ERP, PIM and other back-office systems.

Most headless storefronts use GraphQL for the shopper's journey and leave REST to integrations.

Where the storefront gets catalogue data

There are two approaches.

Query Magento directly. The storefront calls Magento's GraphQL for every category, filter and search. It's simpler to build, but every shopper and every bot still reaches Magento, so the load problem stays.

Keep a separate index. Products are synced from Magento into a search engine such as OpenSearch (catalogue and filters) or Meilisearch (site search), and the storefront reads from there. Magento only handles the cart, checkout and admin. It needs a sync: a module in Magento that picks up changes from the admin, imports and integrations, and a queue such as RabbitMQ that passes them on. In practice, changes go live within a few minutes.

If the reason for going headless is load from bots, ads or reindexing, the second approach is the one that helps.

Choosing the front-end

Any modern framework works. The common choices are React (for example with Next.js) and Vue (for example with Nuxt). What matters more than the framework:

• Server-side rendering. Search engines and AI crawlers must get full HTML. A storefront that renders only in the browser can lose rankings.
• Caching. Pages and API responses need clear cache rules, and a way to clear them when prices or stock change.
• Image optimisation, so images are resized and compressed automatically.

Cart, checkout and prices

The safest setup keeps the cart and checkout on Magento. The storefront may show a cached price, but adding to the cart goes through Magento, which checks the current price and stock. An out-of-stock product can't be ordered, and customer group prices work as before.

A fully headless checkout is possible, but every payment and shipping method has to be rebuilt on the storefront. Start with the catalogue; move checkout later, if at all.

Extensions

Magento extensions that render something on the page were built for the Magento front-end. In a headless store, their front-end part has to be rebuilt: reviews, product labels, banners, related products, stock notifications, chat and email widgets, tracking pixels. Extensions that work only in the back end (ERP sync, payment processing, order logic) keep working.

Make a list of every extension and mark what it shows on the page. It's the biggest single factor in the project's scope.

SEO in a headless Magento store

• URLs. Keep every URL, including those from custom navigation modules. Magento's GraphQL route query resolves a URL to a product, category or CMS page.
• Meta and structured data. Titles, descriptions, canonical tags, product structured data and breadcrumbs move to the storefront.
• Sitemaps and redirects must keep working, including Magento's URL rewrites.
• Measure the same pages before and after launch.

Switching traffic and rolling back

With a CDN such as Cloudflare in front, you can switch one store to the headless storefront at a time, and switch it back to the Magento front-end in minutes if something goes wrong. The cart stays in Magento, so shoppers keep it.

Headless vs microservices

They are different things. Headless separates the front-end from the back end. Microservices split the back end into small, independent services. A headless Magento store usually keeps Magento as one back end and adds a few services around it: the storefront, search and a sync.

Checklist before you start

• Magento version and number of stores (any Magento 2.x works; Magento 1 doesn't).
• Every extension that shows something on the page.
• Integrations that depend on the Magento front-end.
• URL structure, including custom navigation modules.
• The pages and metrics you'll compare before and after.
• Who will run the extra servers and services after launch.

Questions about headless Magento architecture

Is there a headless Magento 2 example to look at?

See our headless commerce for Magento page: a live storefront on a real Magento 2 catalogue, and the stack behind it. For a B2B example, read how we built headless B2B commerce on Magento 2 inside TYPO3.

Can I use Magento's own CMS in a headless store?

Yes. Magento CMS pages and blocks are available through GraphQL. Many teams still move content to a headless CMS, so content editors don't need the Magento admin.

Does headless Magento need a newer Magento version?

No. The storefront works through the API, so any Magento 2.x can go headless. Newer versions have more complete GraphQL coverage.

Is Hyvä an alternative?

For front-end speed, yes. The Hyvä theme makes the Magento front-end much lighter, but it still runs on Magento, so it doesn't take load off the server.

SYSINT has worked with Magento since 2012 and builds headless storefronts for Magento 2 for agencies and online stores. See headless commerce for Magento.