If you’ve shopped on a custom storefront that didn’t look like a stock template, there’s a good chance a headless commerce API was doing the work behind it. A headless commerce API is the interface a commerce backend exposes so any storefront can read products, build carts, and place orders without being tied to a built-in theme. This explainer covers what that means, how it relates to composable commerce and MACH, and why your storefront and partner teams live and die by that API contract. It builds on the idea that software is going headless and your API is now the product.
What “headless” means in commerce
Traditional commerce platforms ship as one piece. The product catalog, the cart, the checkout, and the HTML pages that render them all live in the same system. You theme it, you tweak it, and you ship.
Headless commerce splits that in two. The backend, often called the commerce engine, keeps the catalog, pricing, inventory, cart, and order logic. The frontend, your storefront, becomes a separate app you build however you like. The only thing connecting them is an API.
So the “head” is the presentation layer. Going headless means removing the fixed head and exposing the body, the commerce logic, through an API instead. A React site, a native mobile app, a smart-fridge screen, or a voice assistant can all talk to the same backend because they all speak the same API.
That decoupling is the whole point. Your frontend team picks their own framework and ships on their own schedule. The backend team owns commerce rules. The API is the line between them.
The tradeoff is that you take on more work. A traditional platform hands you a working store out of the box. Going headless means you build and host the storefront yourself, so the flexibility comes with engineering cost. Teams choose headless when a stock theme can’t deliver the experience they need, or when they want to serve several channels from one backend.
Headless vs composable vs MACH
These three terms get used interchangeably, but they describe different scopes. Here’s the honest breakdown.
| Term | What it describes | Scope |
|---|---|---|
| Headless commerce | Frontend decoupled from a single commerce backend, connected by an API | One backend, one or many frontends |
| Composable commerce | The whole stack broken into swappable best-of-breed services (catalog, search, payments, PIM, OMS) | Many independent services assembled together |
| MACH | A set of architectural principles that composable stacks tend to follow | A philosophy, not a product |
Headless is the narrow case. You can be headless with one monolithic backend, as long as the storefront talks to it over an API.
Composable commerce goes further. Instead of one backend, you assemble independent services and pick the best tool for each job. Search from one vendor, payments from another, a separate product information manager. Each is its own service with its own API, and you compose them into one experience.
MACH is the principle set behind most composable stacks. Per the MACH Alliance, an industry group formed in 2020, MACH stands for Microservices, API-first, Cloud-native SaaS, and Headless. Notice that API-first sits right in the middle. In a MACH world, the API isn’t a side feature. It’s the only way the pieces talk to each other, which is the same reasoning behind treating your API as a product.
What a headless commerce API actually exposes
The exact shape varies by platform, but most headless commerce APIs cover the same core jobs:
- Catalog and products. Read products, variants, collections, and media so the storefront can render listings and detail pages.
- Search and browse. Query, filter, and sort the catalog.
- Cart and checkout. Create a cart, add and remove line items, apply discounts, and move toward payment.
- Customers. Sign in, manage accounts, and track order history.
- Inventory and pricing. Surface stock levels and the right price for the right context.
Some platforms split these into a public-facing storefront API and a separate admin API for back-office work. The storefront API is read-heavy and customer-facing. The admin API handles catalog edits, order management, and config.
The protocol matters too. Many headless commerce APIs are GraphQL, which lets the storefront ask for exactly the fields it needs in one round trip. Others are REST, and some platforms offer both. If you’re weighing the tradeoffs, see REST vs GraphQL.
The main platforms
The headless commerce space splits roughly into SaaS engines and open-source engines. A few names you’ll run into:
- commercetools. A founding MACH Alliance member and one of the most-cited composable commerce platforms. API-first and cloud-native by design.
- Shopify. Offers headless builds through its Storefront API, with Hydrogen as a React framework for consuming it. If you’re already in the Shopify world, our Shopify API tutorial is a good starting point.
- BigCommerce. Supports headless mode with GraphQL Storefront and Checkout APIs on top of its catalog. See our guide to using BigCommerce APIs.
- Saleor. An open-source, GraphQL-first engine built on Python and Django.
- Medusa. An open-source engine built on Node.js and TypeScript, popular with JavaScript teams who want full backend control.
Verify platform specifics before you commit, since pricing, hosting models, and API coverage change. The pattern across all of them is the same: the engine exposes commerce logic through an API, and you build the head.
Why teams depend on the commerce API contract
Once the storefront is decoupled, the API stops being plumbing and becomes the agreement everyone builds against. This is where headless gets real.
Your frontend team can’t ship a product page until they know the exact shape of a product response. Your partner integrations, a loyalty app, a tax service, a marketplace feed, all wire into the same endpoints. A mobile team consumes the same contract as the web team. If the response shape changes without warning, every one of those consumers can break at once.
That’s the risk and the opportunity. A clear, stable, well-documented commerce API contract lets independent teams move fast without stepping on each other. A vague or drifting one turns every release into a coordination scramble. The contract is the product, so it deserves the same care as the storefront itself, including contract testing to catch breaking changes before they ship.
Versioning is part of the deal too. When you need to change a product response or rename a field, you can’t just edit the endpoint and hope. Consumers you don’t control are reading it. So headless teams treat the contract as a public commitment: additive changes where possible, clear deprecation windows, and tests that flag anything breaking before it reaches a partner’s integration.
Where Apidog fits
Apidog doesn’t run your store. It isn’t a commerce engine, a CMS, or a gateway, and it doesn’t make your stack headless or composable. What it does is own the API-first pillar of all this: the layer where you design, test, mock, and document the contract that everything else depends on.
That maps cleanly onto headless commerce work:
- Design the contract first. Model the storefront or admin API as an OpenAPI spec in Apidog before code exists, so frontend and backend agree on the shape up front.
- Mock before the backend is ready. Spin up a mock server from the spec so your storefront team builds against realistic product and cart responses while the commerce engine is still being wired up. That’s the decoupling promise made practical, and you can read more in our mock API explainer.
- Test the contract in CI. The Apidog CLI runs your API tests with no GUI, headless test execution that fits a pipeline. It’s a true conceptual rhyme with headless commerce: no front-end needed, just the contract being verified.
- Document it for partners. Auto-generated, interactive docs give your storefront and partner teams one source of truth for the API they’re integrating against.
For a deeper look at why this matters once the API becomes the only interface, see software is going headless and your API is now the product. If you want to try the workflow, download Apidog and import an existing spec.
Frequently asked questions
Is headless commerce the same as composable commerce?
No. Headless commerce decouples the storefront from one commerce backend over an API. Composable commerce goes further and assembles many independent best-of-breed services, each with its own API, into a single experience. Every composable stack is headless, but a headless setup with one monolithic backend isn’t necessarily composable.
Do I need GraphQL for a headless commerce API?
No. GraphQL is common because it lets the storefront request exactly the fields it needs in one call, which suits product and cart rendering well. But plenty of headless commerce APIs use REST, and some platforms offer both. The protocol matters less than the contract being stable and documented.
Can I test a headless commerce API before the backend is built?
Yes, and that’s one of the main reasons to go design-first. If you model the API contract as a spec, you can generate a mock server that returns realistic responses. Your storefront team builds and tests against the mock while the commerce engine is still in progress, then swaps to the real endpoints later.
What is the MACH Alliance?
The MACH Alliance is an industry group formed in 2020 to promote open, best-of-breed technology stacks built on Microservices, API-first, Cloud-native SaaS, and Headless principles. Vendors like commercetools are founding members. MACH is a set of architectural principles, not a single product you buy.
The contract is the store
Headless commerce moves the value from the theme to the API. Once the storefront is decoupled, the commerce API is what your frontend, mobile, and partner teams actually build on. Composable commerce and MACH push that further by making API-first a core principle rather than a nice-to-have.
None of that depends on Apidog, but the quality of the contract does benefit from a place to design, mock, test, and document it. If that’s where your headless project is headed, Apidog gives you that layer without pretending to be the commerce engine underneath.
