Headless is an architecture decision
Headless commerce separates the customer-facing storefront from the commerce application behind it. The storefront communicates with commerce services through APIs rather than relying entirely on the platform's traditional page-rendering layer. That separation can be valuable, but it also creates more boundaries to design, test and operate.
At Midoriweb, we would not recommend headless simply because a store needs a new look or feels slow. First, we want to understand what the business cannot achieve with its current architecture. If the real problem is an inefficient integration, an overloaded application or an unmaintained theme, moving the frontend may leave the important constraint untouched.
This guide helps you assess when the added complexity is justified. It sits alongside our web development and ecommerce services and our performance investigation. The right starting point is the business requirement and the evidence, rather than a commitment to a particular frontend framework.
Identify the requirement that needs separation
Headless can make sense when several experiences need to share commerce capabilities, when a distinctive customer journey exceeds what the existing theme layer can reasonably support, or when separate teams need a carefully designed release boundary. Each reason should be specific enough to test.
For example, “we want flexibility” is too broad. “Our retail storefront and a specialist ordering interface need the same account pricing and basket rules, with different presentation” gives the architecture discussion something concrete. It also reveals the difficult question: can those rules be exposed and used consistently through the available APIs?
A new frontend may improve delivery options for the team, but it does not automatically make the whole business more independent. Payments, promotions, product data and fulfilment remain shared dependencies. Identify those dependencies early so the proposal explains what becomes easier and what still needs coordinated work.
- 01ExperiencePages, interactions and content
- 02API contractPublic data, private state and errors
- 03CommercePricing, stock, basket and orders
- 04OperationsObserve and test the whole journey
Compare the full responsibility of each approach
A conventional storefront keeps more of the presentation and commerce behaviour within an established platform structure. That can simplify compatibility with extensions built for that structure. It still requires careful development and performance work; “conventional” does not mean maintenance-free.
A headless storefront gives the frontend team greater control over presentation and request behaviour. The team also becomes responsible for more integration decisions: how product and customer data are fetched, how errors appear, how private state is handled and how the experience recovers when a dependency is unavailable.
Compare the approaches against your actual workflows. If an extension's main value exists only in its traditional frontend templates, a headless implementation may need additional API and interface work. Check this before counting the extension as a solved requirement. The extension or custom module guide provides a useful evaluation method.
| Responsibility | Conventional storefront | Headless storefront |
|---|---|---|
| Presentation | Theme and platform rendering | Separate frontend and API contract |
| Extensions | Check compatibility with the installed stack | Also verify API and frontend coverage |
| Performance | Measure the complete customer journey | Measure frontend requests and backend work together |
| Release ownership | Coordinate the platform and its dependencies | Coordinate separately deployed but dependent systems |
| Business case | Improve the current experience where practical | Justify separation with a specific requirement |
Worked example: a specialist product configurator
Imagine a fictional merchant selling configurable equipment. Customers choose compatible components, see availability and receive an assembled price. The standard product page is becoming difficult to extend, and the team is considering a separate frontend.
The first task is to identify where the configuration rules belong. If the browser alone decides which components fit, another ordering channel might bypass those rules. If pricing is calculated in multiple places, a basket could disagree with the product experience. The architecture needs an authoritative service or application boundary for rules that affect the order.
A useful proof would demonstrate one representative configuration through product selection, price calculation, basket creation and order acceptance. It would include an incompatible component, a stock change and a failed request. A polished configurator animation without that complete journey does not establish that the proposed architecture works.
Performance depends on request design
Separating the storefront does not remove the cost of retrieving data. A page can still wait on several sequential requests, an expensive operation or an external service. The frontend may render quickly while the customer cannot complete the task that matters.
Review which information is needed for the initial view and which can arrive later. Avoid fetching private or frequently changing data as though it were public catalogue content. Adobe documents specific GraphQL caching behaviour; verify the applicable queries and deployment configuration rather than assuming every API response can be cached in the same way.
Use the Magento GraphQL performance guide when investigating the request path. Compare equivalent journeys under recorded conditions. A framework demonstration or an empty catalogue benchmark is not a forecast for a store with your products, promotions, extensions and customer traffic.
Plan search visibility and content operations
Search visibility needs an explicit acceptance plan. Confirm that important pages expose useful content, correct links, canonical URLs and appropriate indexing directives. Test redirects, pagination, product availability and error responses. Do not treat the choice of a rendering technique as proof that all discovery requirements are covered.
Content teams need an equally practical review. Where will they edit landing pages? How will they preview a change? Can they add a campaign without a developer release? Which system owns menus, product copy and structured content? Moving the storefront should not quietly make everyday publishing harder.
Our ecommerce migration checklist is useful even when the commerce platform stays the same. A storefront replacement still changes URLs, templates, tracking or customer journeys unless the project deliberately preserves them. Record what must survive and verify it before launch.
Include failure behaviour in the design
Decide how the storefront behaves when search is unavailable, a price request fails or a basket update is delayed. The customer needs a clear state and an appropriate next action. A spinner that never ends or a silent retry that repeats a transaction is not an acceptable recovery design.
Session handling, authorisation and customer-specific data need consistent boundaries. Test account switching, expired sessions and navigation between public and private pages. The browser should never receive credentials intended only for server-to-server communication.
Operationally, agree how the team traces a failed journey across the frontend and the commerce application. Correlation references and useful, access-controlled logs make incidents easier to diagnose. Avoid collecting unnecessary customer information just to make debugging convenient.
Price the operating model, not only the build
Include hosting, deployment pipelines, monitoring, dependency updates and the skills needed to maintain both sides of the architecture. Identify who owns incidents that cross the boundary. If the frontend agency and commerce team each regard the other system as outside their responsibility, the customer journey can fall between them.
Agree how API changes are tested and released. A separately deployed frontend still depends on a compatible backend contract. Document supported operations and the acceptance checks that protect product discovery, account behaviour, basket totals and order placement.
The proposal should also explain a practical rollback or phased release approach. A complete rewrite launched in one step carries different delivery risks from a contained experience introduced alongside the existing storefront. Choose the approach around the business constraints and the evidence available.
Make the decision with a focused proof
Before committing to a rebuild, identify the one or two uncertainties most likely to change the architecture decision. Build a representative proof around them, using the real business rules and an appropriate test environment. Record limitations rather than filling gaps with optimistic assumptions.
Proceed when the benefit is specific, the critical journeys work, the integration responsibilities are clear and the business can support the operating model. If those conditions are not met, improving the existing storefront may be the stronger investment.
Bring Midoriweb the customer journey you want to improve and the constraint you are trying to remove. We can assess the architecture in that context and scope the next piece of work. Headless is useful when the separation earns its place in the solution.
Technical references
Use the documentation that matches your installed version and deployment.