Why headless commerce changes the build for a custom storefront
A brand team that wants its own front end usually faces the same trade-off: the storefront becomes code the team owns, but checkout, catalog, pricing and order handling still have to run safely behind it. Headless commerce moves the presentation layer into the team's own code while the commerce API, data model and payment flows stay on the platform. That split changes who builds what, who patches what and where failures show up. A broken template in a monolith is a platform problem, while a broken storefront in a headless build is the team's problem, and the commerce API still has to answer correctly under load.
The short answer is that Saleor and Medusa are API-first, so the commerce engine exists to be called from outside. Saleor exposes everything through a GraphQL API, and Medusa is built with Node.js and TypeScript on PostgreSQL with modules for carts, orders, pricing and inventory. Magento Open Source is a monolith that also exposes a GraphQL layer, so a custom storefront can call it, but the core still renders and governs much of the shop. Confirm which API surfaces your chosen version exposes for cart, checkout and customer actions before you commit to a front-end design, because those gaps are where custom storefronts usually need extra work.
The right choice depends on three things: the skills in your team, the complexity of your catalog and the degree of storefront customization you need. A team with strong TypeScript or React experience and a modest catalog may find an API-first build straightforward. A team with deep PHP experience, existing Magento extensions and a catalog that depends on those extensions may get more value from the monolith's GraphQL layer. Write down your must-have storefront behaviors and test each against the candidate API in a short proof of concept before deciding.
What a headless build must satisfy and what it means for the design
This table lists the requirements that appear once the storefront is separate from the commerce core, with the source of each requirement and the design consequence for the build. Use it to see where a headless design moves responsibility, and mark each row where a QSA, auditor or vendor must confirm the details before work is scoped.
| Requirement | Source and constraint | Build consequence and what to confirm |
|---|---|---|
| API authentication and secrets | Saleor exposes everything through a GraphQL API, and a self-hosted Medusa server and worker each need database credentials plus COOKIE_SECRET and JWT_SECRET values | Storefront tokens, admin credentials and signing secrets must sit in a secrets manager, not in front-end bundles. Confirm with your security team how the storefront authenticates to the API and how keys rotate. |
| Payment page script control and PCI DSS scope | PCI DSS requirement 6.4.3 covers management of payment page scripts, and requirement 11.6.1 covers change detection on payment pages; the checkout design decides which SAQ applies | A headless storefront that renders its own checkout widens the set of scripts you control. Confirm with your QSA whether payment fields are hosted by the provider in an iframe or redirect, since that choice sets SAQ eligibility. |
| Accessibility of the custom front end | The ADA Title II rule requires state and local government web content to meet WCAG 2.1 Level AA, with compliance dates of April 26, 2027 for entities with 50,000 or more people and April 26, 2028 for smaller entities and special districts | Accessibility is no longer inherited from a theme, so the front-end framework and component library must be tested against WCAG. Confirm with your counsel which rule applies to your organization and which dates bind you. |
| Content governance between the CMS and the shop | Saleor and Medusa manage products, prices and inventory in the commerce core, while a headless CMS such as Strapi, Payload or Directus manages editorial content | Assign ownership per field: product facts stay in the commerce core, marketing pages and rich content stay in the CMS. Document which system is the source of truth for each product attribute and how changes sync between them. |
| Upgrade cadence of the API | Saleor 3.23.42 was released on October 16, 2026, and Medusa v2.21.2 was released on September 28, 2026; each project publishes releases on its own schedule | Plan regular API upgrades and test them against the storefront contract. Confirm with the vendor how breaking changes are announced and whether the release pace fits your change-control window. |
| Upgrade cadence of the front end | Front-end frameworks and their dependencies ship independent security fixes on their own schedules, separate from the commerce core | The storefront becomes a second application to patch, scan and redeploy. Confirm who owns dependency updates, how the build pipeline is tested, and how rollbacks are handled. |
| Hosting and runtime footprint | Saleor needs the API, Dashboard, PostgreSQL, Valkey or Redis and Celery workers, and Medusa needs a server, a worker, PostgreSQL and Redis | Each runtime becomes an in-scope system for hardening, logging and backups. Confirm with your auditor which components fall within the evidence set. |
Which API-first platform fits a custom storefront
A custom storefront shifts the platform decision from the shop's admin screens to the API underneath it. The three options below differ in license, language stack, extension model and what your team must run, so the right choice depends on the skills you already have and how much commerce logic you want to own.
Saleor for GraphQL-first commerce
Saleor is BSD-3-Clause licensed and built on Python, Django, GraphQL and PostgreSQL, and it exposes everything through a GraphQL API. It suits teams with Python or Django experience who want a commerce API as the system of record for a storefront built in any framework. Extension runs through webhooks, apps and metadata rather than in-process plugins, so check whether your integrations fit that model. Running it needs the API, the Dashboard, PostgreSQL, Valkey or Redis, and Celery workers, and the Docker Compose setup asks for at least 5 GB of memory.
Medusa for JavaScript teams
Medusa is MIT licensed at its core and built with Node.js and TypeScript on PostgreSQL, with modules for carts, orders, pricing and inventory. It suits teams whose storefront and back end both sit in the JavaScript ecosystem and who want one language across the stack. A self-hosted deployment needs PostgreSQL, Redis, a server instance and a worker instance. Role-based access control in Medusa's Enterprise Edition requires a commercial agreement with MedusaJS, Inc., so confirm early whether your admin access model depends on it.
Magento Open Source for GraphQL on a monolith
Magento Open Source is licensed under OSL-3.0 and provides a GraphQL layer on a full monolithic commerce application, so a headless storefront can reuse an established catalog, checkout and extension ecosystem. It suits organizations with PHP capacity and existing Magento knowledge. Adobe's lifecycle policy gives 2.4.9 standard support through May 31, 2029. The hosting footprint is heavier: the 2.4.9 requirements list PHP 8.5, MySQL or MariaDB, OpenSearch 3, Redis or Valkey, RabbitMQ and nginx. The trade-off is that you carry the whole monolith's upgrade and patch load even when the storefront is headless.
Confirm the team's language skills first
The strongest predictor of a healthy headless build is whether your in-house or partner engineers can maintain the chosen stack for years. Python and Django point toward Saleor, JavaScript and TypeScript point toward Medusa, and PHP with Magento administration experience points toward Magento. Ask each candidate partner to name the engineers who would own the storefront API layer after launch, and to show a working example of a custom storefront on the proposed stack before you commit.
Map the extension and integration model
Each platform extends differently, and that difference drives custom work. Saleor pushes integrations through webhooks and apps, Medusa through its module and workflow system, and Magento through modules and its GraphQL schema. List the ERP, payment, tax and shipping connections you need on day one, then ask how each option delivers them and which ones need custom code that must survive upgrades.
Plan for the operations load
Every option adds moving parts beyond the storefront: background workers, caches, search and message queues. Saleor needs Celery workers, Medusa needs a separate worker instance and Redis, and Magento needs OpenSearch, RabbitMQ and a full-page cache. Ask your partner to document the run book for each component, the upgrade path for each version, and who applies security patches to the API layer and to the storefront framework.
How content and commerce split between a headless CMS and the shop
A brand whose site is mainly magazine-style content, campaigns and landing pages with a small catalog keeps most of its authoring load in the CMS. The shop holds the transactional core, and the CMS is the place where marketing teams publish, schedule and preview pages without touching commerce code. Candidate CMS layers include Strapi, which is MIT licensed except for components under ee directories that form its separately licensed Enterprise Edition; Payload, which is MIT licensed and built on Next.js; and Directus, which is licensed under MSCL-1.0-GPL, permitting internal use and professional services to deploy or host it while restricting competing use.
- CMS holds: articles, campaign pages, banners, landing page sections, brand guidelines and media assets.
- Commerce core holds: prices, stock levels, carts, orders, payment records and customer accounts.
- Reference model: each campaign block that promotes a product stores the product's commerce identifier (SKU or product ID), and the storefront resolves price and availability live from the shop API.
- Editorial workflow: scheduled publishing and preview are CMS features, so confirm which CMS you select supports the approval steps your team uses.
- Licensing: confirm the license terms for the chosen CMS with counsel, especially where the Directus license or Strapi Enterprise Edition features are involved.
Check that every promotional block degrades gracefully when a referenced product is unavailable, and that the editorial team can see which commerce identifiers a page depends on before publishing.
A brand with long product descriptions, comparison content, rich media and merchandising rules needs a clear boundary between the product record in the commerce core and the rich copy around it. Merchandisers often want to manage collections, sort orders and editorial product stories, while the commerce core must stay the source for what is sellable and at what price. The usual pattern is to keep structured attributes and the sellable record in commerce, and to hold long-form copy, imagery guidance and story modules in the CMS, keyed to the same product identifier.
- CMS holds: rich product descriptions, editorial guides, imagery, size and fit narratives and merchandising collections.
- Commerce core holds: SKU, variants, prices per channel, stock per warehouse, tax-relevant attributes and product status.
- Reference model: the CMS entry stores the product slug or SKU; the storefront joins the two at render time, and both sides should be cached with clear invalidation rules.
- Sync risk: a product removed in commerce can still have a live CMS page, so define who retires content and how stale entries are reported.
- Search: decide whether product search reads from commerce, from the CMS, or from a separate search index that both systems feed.
Ask any implementation partner how product and CMS records are kept in step during peak updates, and whether the cache invalidation is tested under load before launch.
A brand running several storefronts, regional sites or brand sites on one shared catalog should treat the commerce core as the single system of record for products, prices and inventory. Each storefront then has its own CMS spaces or content models for editorial content, while sharing the same product identifiers. Saleor models channels with per-channel pricing, currencies and stock, and Medusa supports multiple sales channels and stores in its commerce modules, so the choice of commerce core shapes how much regional logic sits in commerce and how much sits in the CMS.
- Shared commerce data: a single product, warehouse and price model referenced by every storefront.
- Per-storefront CMS data: separate page trees, campaigns and translations for each brand or market, with shared components where brands share a design system.
- Identifiers: use one stable global product identifier across all storefronts and the CMS, so cross-brand reporting and redirects stay consistent.
- Governance: decide who owns shared content, who approves cross-brand campaigns and how content changes propagate.
- Cost: multiple storefronts multiply front-end build, hosting and CMS seats, so budget for each deployed experience, not only for the platform.
Confirm with a partner how each storefront's CMS content is permissioned, and whether the chosen CMS license terms allow the number of instances and users you plan to run.
What headless adds to build and run cost
Headless adds cost in three places at once: a custom storefront to build and maintain, a separate content system to run, and a second set of services that a monolithic store would have bundled together. The first decision is to list every component the architecture needs, then ask a partner to price each one separately, because a headless quote that shows only a single total hides most of the recurring work.
Saleor shows the shape of the run cost. Its stack needs the API, the Dashboard, PostgreSQL, Valkey or Redis, and Celery workers, and the Docker Compose setup asks for at least 5 GB of memory for Docker, according to the Saleor Docker Compose docs. Each of those services has its own patching, backup and monitoring obligations. Medusa adds its own list: a self-hosted deployment needs PostgreSQL, a Redis database, and two Medusa instances, one in server mode for the API and admin dashboard and one in worker mode for background tasks, with S3 for file storage in production, per the Medusa deployment docs. Confirm with the partner how many environments (staging, production, preview) must mirror that footprint, since each one multiplies hosting and test effort.
One-time work covers architecture, the storefront build, and the integration of the CMS, commerce API, search and payments. Recurring work covers hosting for each service, security patching, dependency upgrades for the front-end framework and the commerce API, and regression testing after each change. The cost of keeping two upgrade tracks in step is often the largest recurring item, so ask how the partner will test a commerce API release against the storefront before it reaches production. Request a quote that separates one-time and recurring lines for storefront, CMS, search, caching, pipelines and monitoring, and states who holds the on-call duty for each. No fee or effort figure is given here; the quote should follow from your written scope.
How a headless commerce rollout runs in phases
A headless commerce rollout moves from a written platform decision to a tested, cut-over storefront and a run plan, with each phase producing a document or test result the next phase depends on. The sequence keeps the API, storefront and payment design under review before any customer traffic reaches them.
Confirm scope and record the platform decision
The team agrees the business requirements, channels, markets, catalog size and integrations, then compares the candidate platforms, such as Saleor, Medusa, or Magento's GraphQL layer, against those requirements. DeployOpen documents the outcome in a decision record that states why the chosen platform fits, what was rejected and why, and which open questions remain. The step is done when the business owner and technical lead have both signed the record.
Design architecture and environments in your infrastructure
The architecture is designed for your own cloud accounts, data center or private network, covering the commerce API, dashboard, database, cache or queue, background workers, the storefront host, the headless CMS, search and object storage. The design also sets out the environments (development, staging, production), secrets handling and backup approach. The output is a reference architecture diagram and an environment specification that your infrastructure team reviews before any build starts.
Model catalog and orders and define API contracts
The team maps the product, price, channel, currency, stock and order data model to the platform's native objects, and identifies where extra attributes or metadata are needed. It then writes the API contracts the storefront and integrations will call, including queries, mutations, webhooks and error behavior. The output is a data model document and a versioned API contract that the storefront team and the ERP or PIM owners both sign off.
Build the storefront with payment and script review
The storefront is built on the chosen front-end framework against the agreed API contract, with content pulled from the headless CMS where editorial pages are needed. Checkout design is reviewed early, including whether payment pages are hosted by the provider or embedded, and every third-party script is inventoried and justified. The output is a working storefront build, a script and payment flow inventory, and a list of checkout decisions that the compliance lead has reviewed for PCI DSS scope.
Test the API and storefront security
Security testing covers the commerce API, authentication and authorization between storefront, dashboard and services, webhook signatures, rate limits, the storefront's headers and content security policy, and the checkout flow. Findings are triaged by severity, fixed, and retested. The output is a written test report listing findings, fixes and retest results, which the release owner must accept before go-live.
Run in parallel and cut over
Before cutover, the new storefront runs alongside any existing shop, with orders, stock and payments reconciled between the two systems for a period agreed in the plan. Load testing, rollback steps, DNS and redirect changes, and the order freeze window are rehearsed. The output is a cutover runbook and a reconciliation report, and cutover proceeds only when the reconciliation shows no unexplained differences.
Operate through hypercare and plan upgrades
After go-live, the team watches error rates, order flow, webhook delivery and integration health for an agreed hypercare period, fixing issues as they appear. The handover includes an operations runbook, monitoring and alert setup, backup and restore tests, and an upgrade plan tied to the vendor's release and support policy. The output is a signed handover pack and a dated upgrade calendar that your team or a retainer partner owns.
Evidence that auditors and security reviewers ask for in a headless build
This table maps each piece of evidence an assessor or security reviewer typically asks for to the component that produces it in a self-hosted headless commerce stack. Read it as a collection plan: confirm each row with your auditor before work starts, because DeployOpen prepares this evidence but independent auditors and certification bodies issue any report.
| Evidence | What it shows | Where it comes from |
|---|---|---|
| Deployment configuration and environment variables | Which settings the API, Dashboard and workers run with, following 12-factor practice | Saleor configuration through environment variables, Medusa server and worker environment files, under version control |
| Secret management records | Who holds COOKIE_SECRET and JWT_SECRET, how they are rotated, and that they are not in source code | Secret store audit logs and rotation tickets for Medusa server and worker, plus database credentials |
| Health check results | The API and worker respond as expected after each deployment | Medusa /health endpoint results, uptime monitor history and deployment pipeline logs |
| Dependency and version inventory | Exact versions of Saleor 3.23.42, Medusa v2.21.2 or Magento 2.4.9 and their runtime components | Lockfiles, container image digests, software bill of materials and the release notes for each version |
| Payment page script inventory and change detection | Which scripts load on checkout and that unexpected changes are detected and reviewed | Script inventory export, change detection alerts and review records for each storefront release |
| API security test reports | Results of authentication, authorization and input testing on the GraphQL or REST API | Penetration test reports, scan outputs and remediation tickets, retained with retest results |
| Backup and restore tests | Backups of PostgreSQL, media storage and configuration can be restored within the agreed recovery targets | Restore test logs, dated runbook executions and the recovery time observed in each test |
| Upgrade and patch change records | Each platform upgrade, such as Magento 2.4.9 with support through May 31, 2029, is planned, tested and approved | Change tickets, staging test results, release notes and the vendor support timeline on file |
Questions to ask an implementation partner about headless commerce
Start with the platform and the team. Ask the partner which of Saleor, Medusa, or Magento Open Source they recommend for your catalog size, channels and in-house skills, and why, in writing. A credible answer names the tradeoffs: Saleor exposes everything through a GraphQL API and extends through webhooks and apps, Medusa is built on Node.js and TypeScript with its own module model, and Magento keeps a monolithic storefront with a GraphQL layer on top. Ask who on the partner side will test the storefront against the commerce API, which test layers they will run (contract, integration and end-to-end), and who owns the API contract once it is published. Ask who approves a breaking change to a field, mutation or webhook payload, and whether the storefront team gets a deprecation window before it ships.
Next, ask about payment pages, upgrades and sizing. Ask how the storefront will keep payment scripts under control, including whether card data passes through your domain or only through a payment provider's hosted fields, and which party maintains the script inventory and change detection. Ask how the partner upgrades the commerce API, the background workers and the front end, and whether these run on separate release tracks with separate test gates. Confirm that a Saleor or Medusa deployment includes a worker process, and ask how cache and search are sized for your peak traffic. Ask for the load test plan and who runs it. For order and catalog migration, ask how product, customer and open order data will be mapped and reconciled, and what is cut over at go-live.
Finish with the written boundary. Ask for a scope that lists each deliverable, the environments you receive, and the acceptance criteria for each. Ask who applies security patches after go-live, how fast critical fixes are applied, and whether that work sits in a retainer or a separate change request. Make sure the document names the parts that stay with your team, such as content entry, product data quality, payment provider accounts and business rules, and who holds the secrets, hosting accounts and monitoring alerts. Request a list of platform versions the partner will pin and the support window for each, verified against the vendor's current release and support pages before you sign. Ask for the quote to be derived from that scope so that you can compare partners on the same basis.
Questions buyers ask before hiring help with headless commerce
How much more does headless cost than a monolith?
Headless usually adds cost in the storefront build, the separate services you run, and the integration work between them, so the gap depends on how much custom front end you commission. A monolith such as Magento Open Source or WooCommerce bundles the storefront with the commerce engine, while a headless build on Saleor or Medusa needs a separate front end, a content layer, hosting for each part and a tested API contract between them. Costs that recur include hosting for the API, the Dashboard or admin, PostgreSQL, a cache or queue, workers, the front end and the content system, plus monitoring and upgrades for each. Ask any partner for a written split of build, hosting, integration and run costs, with the monolith alternative priced on the same scope so you can compare them directly.
How long does a headless commerce build take?
Timing depends on the number of storefront templates, the catalog and data migration, the integrations with payments, ERP and search, and how much of the content model is new. No researched figure is available here, so treat any duration in a proposal as a claim to test. Ask the partner to break the timeline into discovery, API configuration, storefront build, integration, testing, a pilot or soft launch, and cutover, with a named dependency for each phase. Where the scope is agreed in writing before work starts, you can compare proposals on the same deliverables rather than on headline dates.
What must our team provide during a headless build?
Your team usually supplies decisions and access rather than most of the code. Expect to provide a product data owner who can approve the catalog model, a content owner for the headless CMS, an integration owner for payments, ERP and shipping, access to sandbox and production environments, and a sign-off process for design and checkout. Your security team should also name who approves cloud accounts, secrets management, and the network paths between the storefront, API and payment providers. Put these responsibilities into the written scope with named roles and response expectations, because delays in these areas are a common reason headless projects slip.
Can our developers run the headless store after handover?
Yes, if the handover includes documentation, runbooks, configuration in version control and a tested upgrade path, and if your team has skills in the stack, which typically includes Node.js and TypeScript for Medusa, Python and GraphQL for Saleor, and a modern front-end framework for either. Your developers will need to operate a database, cache, queue, workers and deployment pipeline, not only the storefront code. Agree in writing what remains with your team, what remains with DeployOpen under a retainer, and what is covered by a support or upgrade agreement. DeployOpen supports ongoing support, upgrades and continuous testing as retainers.
Is Saleor or Medusa easier to support?
Neither is simpler by default, because support effort depends on your team's skills, hosting model and how many customizations you add. Saleor is built on Python, Django, GraphQL and PostgreSQL, and extends through webhooks, apps and metadata rather than in-process plugins, which keeps custom logic outside the core. Medusa is built on Node.js and TypeScript with PostgreSQL, and a self-hosted deployment needs two Medusa instances (one for the API and admin, one for background workers), plus Redis and S3 in production. Choose based on which language your team already supports, and ask each candidate to show how an upgrade, a failed migration and a worker outage are handled in your environment. Check licensing too, since Medusa's Enterprise Edition features based on role-based access control require a commercial agreement.
Does headless remove our PCI DSS work?
No. Headless changes where the PCI DSS scope sits, but it does not remove it. Your PCI DSS scope depends on how card data is collected, which means whether the payment page is hosted by a provider, embedded in an iframe, or built by your own team. The storefront is often the part that handles scripts and payment pages, so the choice of front-end framework and third-party scripts matters as much as the commerce engine. Ask the partner how payment page scripts are managed and how changes to those pages are detected, and get your qualified assessor involved early. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports or attestations, and independent assessors make that determination.
How DeployOpen scopes and supports a headless commerce build
DeployOpen plans, implements, customizes, integrates, hardens, documents and supports self-hosted open-source commerce platforms inside your own cloud accounts, data centers or air-gapped networks. For headless commerce, that means the commerce API, the storefront, the content layer and the integrations are treated as one system with a written scope agreed before work starts.
How we scope
- Map which catalog, pricing, cart and order functions the commerce API owns and which content the headless CMS owns.
- Record the chosen platform, such as Saleor or Medusa, with its hosting model and the version pinned for launch.
- Agree the front-end framework, rendering approach and channels in writing before design or build begins.
- Document payment provider integrations, PCI DSS scope assumptions and the hosting boundary in the statement of work.
- Engagements are fixed-scope, so deliverables and timelines are written down before work starts and quoted from that scope.
How we build
- Stand up the commerce API, dashboard, PostHog-free database, cache, queue workers and storage in your environment.
- Configure channels, currencies, warehouses, promotions and webhook or app extensions instead of forking core code.
- Build the storefront against the commerce API and wire content from the headless CMS through versioned, documented contracts.
- Test API contracts, checkout paths, search and page performance, and accessibility of storefront templates before release.
- Run security testing on the API, storefront and integrations, and record findings and fixes in the project file.
How we hand over
- Deliver runbooks for deployment, database migrations, secret rotation, backups and restore testing.
- Document environment variables, service dependencies and the health checks used to confirm each deployment.
- Provide architecture diagrams, data flow maps and the list of integrations with their owners and credentials locations.
- Train your engineers on the storefront build pipeline, webhook handling and content model changes.
- Hand over evidence for compliance readiness, such as access records, change logs and configuration baselines.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- Plan platform upgrades against the vendor release cadence and test them in staging before production.
- Track security patches for the commerce API, storefront framework, CMS and their dependencies.
- Review performance and capacity ahead of seasonal peaks, with load testing agreed in the retainer scope.
- Ask any partner which upgrade, patch and incident response terms apply in writing before signing.
