How to Build a Headless Commerce Platform From Scratch 2026

Traditional commerce platforms bundle the frontend, backend, and database into one tightly coupled system. That works until it does not. You want a React storefront, but the platform only renders server-side templates. You need sub-100ms API responses for a mobile app, but the monolith returns 800ms page loads with no way to optimize. You want to sell through a kiosk, a voice assistant, and a partner's embedded widget, but the platform assumes a single web store.

Headless commerce solves all of these problems by decoupling the presentation layer from the commerce engine. The backend exposes APIs for products, carts, orders, and payments. The frontend consumes those APIs and renders whatever experience you want, on whatever device or channel you want. You are no longer constrained by someone else's template system.

The performance gains alone justify the shift. Headless storefronts built on Next.js or Remix consistently hit Lighthouse scores above 95, with Time to First Byte under 200ms when deployed to edge networks. That speed directly translates to revenue. Google's research shows that each additional 100ms of load time reduces conversion rates by roughly 1%. When you control both sides of the stack, you can optimize aggressively and keep those milliseconds low.

The brands proving this out are not small experiments. Nike, Target, and Sephora all run headless architectures in production. So do fast-growing DTC brands that need to iterate on their storefront weekly without touching their order management or inventory systems. If you are building something that needs to scale beyond a single storefront or a single market, headless is the architecture to bet on.

MACH stands for Microservices, API-first, Cloud-native, and Headless. It is not just a buzzword. It is a set of architectural principles that determine whether your commerce platform stays flexible for years or calcifies into legacy software within 18 months.

Microservices. Each domain runs as an independent service. Product catalog, cart, checkout, inventory, order management, and payments each live in their own deployment unit. When Black Friday traffic spikes, you scale cart and checkout independently without burning money on oversized infrastructure for the catalog service that is mostly serving cached data. A bug in the recommendation engine does not take down checkout.

API-first. Every capability is exposed through well-documented APIs before any UI is built. When the product catalog API is a first-class contract, building a second storefront or a wholesale portal becomes a matter of calling existing endpoints rather than reverse-engineering a monolith. Use OpenAPI 3.1 specs for REST or a strong schema for GraphQL. Generate client SDKs automatically so frontend teams never guess at request shapes.

Cloud-native. Your services run in containers on Kubernetes or serverless platforms like AWS Lambda and Cloudflare Workers. Infrastructure scales automatically. Use managed databases (AWS RDS, PlanetScale, Neon) so you are not babysitting PostgreSQL replication at 2 AM.

Headless. The frontend is completely independent of the backend. Your Next.js storefront, your React Native mobile app, and your in-store kiosk all consume the same commerce APIs. Redesigning the storefront requires zero backend changes.

The power of MACH is composability. You can use Stripe for payments, Algolia for search, Sanity for content, and your own custom service for product catalog. When a better search engine emerges, you swap it without rewriting your checkout flow. That flexibility compounds over years.

The product catalog is the heart of any commerce platform, and getting the data model right at the start saves you from painful migrations later. A headless catalog needs to serve multiple frontends, support complex product relationships, and handle thousands of SKUs without performance degradation.

Entity hierarchy. Start with three core entities: Product, Variant, and SKU. A Product is the logical item ("Running Shoe X"). A Variant represents a specific combination of options (Size 10, Color Black). A SKU is the physical, trackable unit in your warehouse. This three-tier model handles everything from simple single-option products to complex configurable goods with dozens of attribute combinations.

Flexible attribute system. Do not hardcode product fields. Build an attribute schema that lets merchants define custom properties per product type. A clothing store needs size, color, and material. An electronics store needs voltage, compatibility, and warranty length. Use a JSON column in PostgreSQL (with GIN indexing for queries) or a dedicated attribute table with an EAV pattern. The JSON approach is simpler and performs well for catalogs under 100,000 SKUs.

Category and taxonomy. Implement categories as a tree structure using materialized paths in PostgreSQL (storing the full path as a string like "clothing/shoes/running"). Support cross-category assignment so a product can appear in both "Sale" and "New Arrivals" without duplication.

Search and filtering. PostgreSQL full-text search works for catalogs under 50,000 products. Beyond that, offload to Algolia, Meilisearch, or Typesense for instant, typo-tolerant results with faceted filtering. Sync product data to the search index on every update using a background job queue (BullMQ or Temporal).

Media management. Store media references in your product database but serve assets through Cloudinary or imgix for resizing, format conversion (WebP, AVIF), and global CDN delivery. Your API should return image URLs with transformation parameters so each frontend requests the exact size it needs.

Design your catalog API to support both listing queries (paginated, filtered, sorted) and detail queries (single product with all variants and media). Use cursor-based pagination for listing endpoints. It performs dramatically better than offset-based pagination on large datasets.

The cart and checkout flow is where revenue is won or lost. In a headless architecture, these are backend APIs that any frontend can consume. The complexity lives in state management, price calculation, and payment orchestration.

Cart API design. Your cart service needs to handle adding items, updating quantities, removing items, applying discount codes, calculating shipping rates, and computing taxes. Store carts in Redis for speed (sub-5ms reads) with periodic persistence to PostgreSQL for durability. Each cart mutation should return the full, recalculated cart state so the frontend never has stale pricing data. Support both authenticated carts (tied to a user ID) and anonymous carts (tied to a session token), with a merge operation when an anonymous user signs in.

Price calculation engine. Centralize all pricing logic in a single service. This engine handles base prices, volume discounts, promotional pricing, coupon codes, tax calculation, and shipping costs. Never let the frontend calculate prices. The server is the source of truth. A typical price calculation pipeline looks like this: base price, then variant price adjustments, then quantity discounts, then coupon application, then tax calculation (via TaxJar or Avalara), then shipping rate lookup (via EasyPost or ShipEngine), then final total.

Checkout as a state machine. Model your checkout as an explicit state machine: cart_ready, shipping_selected, payment_pending, payment_processing, payment_confirmed, order_created, order_failed. Each transition has validation rules. You cannot move to payment_processing without a valid shipping address. This pattern prevents the "half-completed order" bugs that plague loosely structured checkout flows.

Payment orchestration. Do not hardcode a single payment provider. Build an orchestration layer that abstracts Stripe, Adyen, PayPal, and BNPL providers (Klarna, Affirm) behind a unified interface. Stripe is the default for most startups because its developer experience is unmatched, and Stripe Elements handles PCI compliance by keeping card data off your servers. Adyen is better when you need local payment methods across 30+ countries (iDEAL in the Netherlands, PIX in Brazil). Your orchestration layer should support payment method routing: credit cards to Stripe, European bank transfers to Adyen, BNPL to Klarna.

Idempotency and failure handling. Payment operations must be idempotent. If a customer double-clicks "Pay" or the network drops mid-transaction, your system must not create duplicate charges. Use idempotency keys on every payment API call. Run a reconciliation job every 15 minutes to catch discrepancies between your order database and your payment provider's records.

Once a payment clears, the order management system takes over. In a headless architecture, order management is its own service with its own database, communicating with inventory, fulfillment, and notification services through events.

Order lifecycle. Orders move through a defined lifecycle: created, confirmed, processing, shipped, delivered, completed, cancelled, refunded. Each transition triggers side effects. "Confirmed" reserves inventory. "Shipped" sends tracking info. "Cancelled" releases reserved stock and initiates a refund. Model these transitions using an event-driven architecture with RabbitMQ, AWS SQS, or Kafka.

Inventory as a ledger. Do not store inventory as a single "quantity" integer that you increment and decrement. That creates race conditions and makes auditing impossible. Instead, model inventory as a ledger of transactions. Each stock receipt, reservation, shipment, return, and adjustment is an immutable event. Available quantity is calculated: on_hand minus reserved minus shipped plus returned. This ledger approach gives you a complete audit trail.

Multi-warehouse support. If you ship from multiple locations, each warehouse needs its own stock ledger. Order routing logic decides which warehouse fulfills each order based on proximity, stock availability, and shipping cost. A simple proximity-based router reduces average shipping costs by 15 to 25 percent compared to single-warehouse fulfillment.

Real-time inventory sync. When you sell on multiple channels (your storefront, Amazon, wholesale partners), inventory must stay synchronized in near real-time. Use webhooks or polling to pull stock updates from external channels, and publish inventory change events that all connected systems consume. High-velocity sellers need sub-minute sync to prevent overselling.

Returns and refunds. Build a self-service returns API from day one. Customers initiate a return, receive a shipping label, and the system tracks the return shipment. When the warehouse confirms receipt, the refund is automatically processed through the original payment method.

One of the strongest arguments for headless commerce is multi-storefront capability. A single commerce backend can power a DTC website, a wholesale portal, a mobile app, a marketplace seller page, and an in-store kiosk. Each frontend is independently built, deployed, and optimized for its audience.

Storefront registry. Maintain a registry of connected storefronts with configuration for each: currency, language, pricing tier, available product catalog subset, and checkout rules. Your wholesale storefront shows net pricing and supports purchase orders. Your DTC storefront shows retail pricing and supports credit card payments. Both hit the same product catalog API but receive different price calculations based on their storefront context token.

Content management. Headless commerce needs a headless CMS. Sanity, Contentful, or Strapi manage editorial content (landing pages, blog posts, promotional banners) separately from product data. Your frontend fetches product data from the commerce API and editorial content from the CMS, then composes them into a unified page. This separation lets your marketing team update homepage banners without involving engineering.

Localization and multi-currency. Store prices in the smallest currency unit (cents for USD, yen for JPY) to avoid floating-point errors. Use a currency conversion service that updates exchange rates daily. Tax calculation varies wildly by jurisdiction, so rely on Avalara or TaxJar rather than maintaining tax tables yourself.

Edge rendering for global performance. Deploy storefronts to edge networks using Vercel, Cloudflare Pages, or Netlify. Static product pages are generated at build time and served from the nearest CDN edge node. Dynamic data (cart, pricing, inventory) is fetched client-side from your commerce API. For high-traffic storefronts, use ISR (Incremental Static Regeneration) in Next.js to rebuild product pages every 60 seconds without a full site rebuild.

API gateway. Put an API gateway (Kong, AWS API Gateway, or Cloudflare Workers) in front of your microservices. The gateway handles authentication, rate limiting, request routing, and response caching. Each storefront gets its own API key with scoped permissions, so the wholesale portal accesses bulk pricing endpoints that the DTC storefront cannot.

You do not have to build every piece from scratch. The headless commerce ecosystem has matured significantly, and several open-source and managed platforms give you a substantial head start. The question is how much flexibility you need versus how quickly you need to launch.

Medusa.js is the most developer-friendly open-source option in 2026. It is a Node.js commerce engine with a modular architecture that lets you extend or replace any core module. Product catalog, cart, order management, and payments are all built-in, with a plugin system for extending functionality. Medusa 2.0 introduced a significantly improved architecture with better module isolation and a powerful workflow engine. You own and host the code, which means full control but also full operational responsibility. Best for teams with strong backend engineering that want to customize deeply without vendor lock-in.

Saleor is a Python/Django-based headless commerce platform with a GraphQL-first API. It has excellent multi-channel support, robust permissions, and solid internationalization out of the box. The tradeoff is that customizing the core requires Python expertise, and the Django ORM can bottleneck at very high transaction volumes. Best for teams already in the Python ecosystem or those who prefer GraphQL over REST.

Shopify Hydrogen takes a different approach. It is Shopify's React-based framework for building custom storefronts that connect to Shopify's backend. You get Shopify's bulletproof checkout, payment processing, and order management, but you build your own frontend with full creative control. The limitation is that you are still on Shopify's backend. You cannot swap in a different payment provider or customize the order management workflow beyond what Shopify allows. Best for brands that want Shopify's operational reliability with a custom frontend experience. Not ideal if you need deep backend customization.

Our recommendation: if you are testing product-market fit, use Medusa or Hydrogen to get to market in 8 to 12 weeks. If you are differentiating on backend capabilities (custom pricing logic, proprietary fulfillment, complex B2B workflows), build your own engine using the MACH principles in this guide. Open-source platforms save you 3 to 6 months on commodity features, freeing your team to focus on differentiation.

For a deeper comparison of these approaches, read our breakdown of headless commerce vs. Shopify vs. custom ecommerce.

Performance in headless commerce is not abstract. It directly correlates with revenue. Here are the benchmarks your platform should hit and the architecture patterns that get you there.

Target benchmarks.

• Product listing API: under 50ms at the 95th percentile for paginated queries with filters
• Product detail API: under 30ms at the 95th percentile for single product with all variants
• Cart operations (add, update, remove): under 100ms at the 95th percentile
• Checkout initiation: under 200ms at the 95th percentile
• Storefront Time to First Byte: under 200ms globally via edge rendering
• Largest Contentful Paint: under 1.5 seconds on mobile
• Search results: under 50ms for autocomplete, under 100ms for full search with facets

Caching strategy. Use a multi-layer cache. Product data that changes infrequently (descriptions, images, categories) is cached at the CDN edge with a 60-second TTL and invalidated on update. Frequently changing data (prices, inventory counts) is cached in Redis with a 5-second TTL. Cart data lives in Redis with no caching layer on top, since every mutation needs to reflect immediately. This layered approach reduces database load by 90% while keeping data fresh enough for commerce accuracy.

Event-driven architecture. Use an event bus (Kafka, AWS EventBridge, or RabbitMQ) for communication between services. When a product is updated, the catalog service publishes a ProductUpdated event. The search indexer, the CDN cache invalidator, and the analytics service all consume that event independently. This decoupling means adding a new consumer (say, a price comparison feed) requires zero changes to the catalog service.

Database per service. Each microservice owns its database. The product catalog uses PostgreSQL with JSON columns. The cart service uses Redis. The order service uses PostgreSQL with strong transactional guarantees. The search service uses Meilisearch or Elasticsearch. This isolation prevents one service's query patterns from degrading another's performance.

Circuit breakers and graceful degradation. When a downstream service fails (the tax calculator is down, the shipping rate API times out), your checkout should not crash. Implement circuit breakers that fall back to cached or estimated values. Show estimated tax with a note rather than a 500 error. This resilience pattern keeps revenue flowing during partial outages.

These are not theoretical targets. We have hit these benchmarks on production headless commerce platforms handling thousands of concurrent users. Measure from the start and treat performance as a feature, not an afterthought.

Building a headless commerce platform is a significant investment, but the payoff in flexibility, performance, and long-term ownership is substantial. Here are realistic cost and timeline ranges based on our experience building these systems.

• Headless MVP with open-source engine (10 to 14 weeks): $50K to $90K. Medusa or Saleor backend, custom Next.js storefront, Stripe payments, basic product catalog, cart and checkout, order management. Gets you to market fast with room to extend.
• Custom headless platform (16 to 24 weeks): $120K to $220K. Purpose-built commerce APIs, multi-storefront support, payment orchestration (Stripe plus one additional provider), inventory management with multi-warehouse support, admin dashboard, search integration, and full CI/CD pipeline.
• Enterprise composable commerce (24 to 36 weeks): $250K to $450K+. Full MACH architecture with independently deployable microservices, B2B and B2C support, multi-currency and multi-language, ERP integration, advanced analytics, custom fulfillment logic, and dedicated mobile apps.

For a detailed breakdown of development costs, check our guide on how much it costs to build a web app.

Monthly operational costs to plan for:

• Cloud infrastructure (AWS, GCP, or Vercel): $300 to $3,000 depending on traffic and services
• Payment processing: 2.9% plus $0.30 per transaction (Stripe), variable for Adyen
• Search service (Algolia or Meilisearch Cloud): $50 to $800 per month
• CDN and media (Cloudinary, Cloudflare): $50 to $500 per month
• Headless CMS (Sanity, Contentful): $0 to $500 per month depending on plan
• Monitoring and observability (Datadog, Sentry): $100 to $500 per month

Brands migrating from monolithic platforms to headless architectures consistently report 20 to 40% improvements in page load speed and 10 to 25% lifts in conversion rate. The switch typically pays for itself within the first year.

Start by auditing your current platform's limitations. Then decide whether an open-source engine like Medusa gets you far enough or whether your use case demands a fully custom build. If you are building an ecommerce app from scratch, a headless approach gives you the strongest foundation for long-term growth.

Book a free strategy call and we will map out the right headless commerce architecture for your business, your timeline, and your budget.