Pure Headless vs Hybrid

The difference between pure headless and hybrid WooCommerce is not philosophical — it is operational. Each configuration makes different commitments about checkout ownership, plugin compatibility, deployment complexity, and long-term maintenance cost. Choosing between them without understanding those commitments is one of the most consistent sources of headless WooCommerce project failures.

WooCommerce checkout executes inside the WordPress PHP runtime through a sequence of hooks. This execution model is the constraint that forces a choice between the two architectures. A pure headless setup moves checkout to the frontend application; a hybrid setup keeps checkout in WordPress while the storefront lives elsewhere. Every other difference between the two models follows from that single decision.

Defining Pure Headless

In a pure headless WooCommerce setup, WordPress serves no visitor-facing routes. The frontend application — typically a Next.js application — owns every page the customer sees: product listings, product detail pages, search, cart, checkout, and order confirmation. WooCommerce is accessed entirely through its REST API. The WordPress Admin interface remains available to merchants for product and order management, but visitors never interact with WordPress directly.

Cart state and session management must be handled independently of the WordPress session system. The frontend application either manages cart state in browser storage and synchronizes with WooCommerce at checkout, or proxies cart operations through the frontend server to preserve session cookies. Neither approach is trivial, but both are achievable.

The checkout UI and the checkout logic are both owned by the engineering team. Submitting a checkout means making the right combination of API calls to WooCommerce in the right order, handling validation errors from multiple sources, and managing the payment flow including gateway redirects and order confirmation.

Defining Hybrid

In a hybrid setup, WordPress continues to serve specific routes — typically the cart, checkout, account pages, and order confirmation. The React application handles the storefront: product listings, product detail pages, category pages, and search. At the checkout boundary, the storefront links the customer into the WordPress-served checkout flow.

This means two deployment targets: the Next.js frontend and the WordPress server. They typically live on separate domains or subdomains, which creates a cross-domain boundary for cookies and session state. A customer browsing the storefront on one origin and checking out on another requires deliberate infrastructure to maintain session continuity across that boundary.

The checkout itself runs entirely within WordPress. All WooCommerce PHP hooks execute as designed. The merchant experience of checkout — the fields, the flow, the order confirmation — is unchanged from a non-headless WooCommerce installation.

Checkout Ownership

In a pure headless setup, the engineering team owns the complete checkout experience: the form fields, the validation logic, the coupon application interface, the shipping rate display, the payment method selection, the error states, and the order confirmation. Every edge case that WooCommerce handles natively — address normalization, coupon stacking rules, partial payment scenarios, digital product delivery — must be handled in the custom checkout or it is handled incorrectly.

WooCommerce has been handling these edge cases through many years of development and real-world use. A custom checkout starts from zero. The gap between what the custom checkout handles correctly at launch and what WooCommerce handles correctly by default is the immediate technical debt the team has taken on.

In a hybrid setup, WooCommerce owns the checkout entirely. The engineering team owns the handoff — the point where the storefront links the customer into the WordPress checkout, including passing any cart state across the domain boundary. The checkout UI, the checkout logic, and the edge case handling are all inherited from WooCommerce.

Plugin Compatibility

Most WooCommerce plugins that affect the checkout process work by registering PHP hooks inside the WordPress runtime. These hooks inject additional form fields, modify shipping rate displays, apply conditional discount logic, add payment method restrictions, or extend the order processing sequence. The plugins assume WordPress is generating the checkout page — that assumption is what makes them work.

In a pure headless setup, these plugins have no effect on the custom checkout. Their hooks fire in the WordPress process, but the checkout page is rendered by the frontend application which never receives that output. A checkout plugin that adds a custom field to the WooCommerce checkout form does not add a field to the headless checkout. If the store relies on that plugin for business logic — a tax exemption field, a subscription option, a gift message — that logic must be reimplemented in the custom checkout.

In a hybrid setup, all WooCommerce checkout plugins continue to work because WordPress is still rendering the checkout. Plugins that extend checkout with new fields, new payment methods, or new business logic remain fully functional. The plugin ecosystem the store has built on is preserved.

Plugins that work through the REST API — analytics integrations, CRM connectors, shipping rate providers with API endpoints — are available in both models. The distinction applies specifically to plugins that hook into the checkout render cycle.

Operational Differences

A pure headless setup has one customer-facing deployment: the frontend application. There is no cross-domain boundary in the customer flow. Session management, while complex, is the responsibility of the frontend team and lives entirely within their system. DNS configuration is simpler. CORS is not a concern for the checkout flow because there is no second origin for the checkout to live on.

A hybrid setup has two deployments the customer interacts with. The handoff from the storefront to the WordPress checkout requires session state to transfer across the domain boundary. This typically involves setting cookies that are readable across subdomains, using a server-side proxy for session operations, or generating a temporary authentication token at handoff that WordPress can exchange for session state. These are solvable engineering problems, but they require deliberate design and ongoing maintenance.

Both models require maintaining a WordPress server. The difference is whether the WordPress server also handles customer-facing checkout routes. In a hybrid model, the WordPress server is in the critical path of checkout completion and must be treated accordingly in terms of availability, performance monitoring, and incident response.

Maintenance Cost Over Time

A pure headless checkout accrues maintenance debt over time in two directions. First, WooCommerce evolves — its internal data model, its REST API behavior, and its checkout process change across versions. A custom checkout built against one version of WooCommerce may need updates when WooCommerce changes. Second, the store requirements evolve — new payment methods, new discount types, new shipping logic — and each addition must be implemented in the custom checkout rather than in a WooCommerce plugin.

A hybrid setup distributes maintenance differently. The checkout itself is maintained by WooCommerce. The engineering team maintains the session handoff, the cross-domain cookie configuration, and the frontend storefront. When WooCommerce updates its checkout, the update is available through a plugin upgrade rather than a custom code change. When a new payment method is needed, it can often be added through a WooCommerce payment plugin.

Neither model eliminates maintenance — they distribute it differently. Pure headless concentrates maintenance in checkout code the team owns. Hybrid spreads maintenance across two systems and a coupling point between them.

Decision Criteria

Hybrid is generally the lower-risk starting point. It preserves the WooCommerce checkout the team already understands, keeps plugin compatibility intact, and limits the custom engineering work to the storefront and the cross-domain handoff. Teams that later determine their requirements justify a custom checkout can migrate from hybrid to pure headless with a clear scope.

Pure headless is the right choice when the team has strong frontend checkout engineering capacity, the store has few or no checkout-affecting plugins, and the requirements for the checkout experience are specific enough that WooCommerce native checkout would need significant customization regardless. In those conditions, the maintenance cost of a custom checkout may be comparable to the maintenance cost of heavily customizing the WordPress checkout.

Teams choosing between these models should be honest about two things: how many WooCommerce plugins the store currently relies on for checkout behavior, and how much frontend checkout engineering capacity exists on the team. These two factors, more than architectural preference, determine which model a team can execute successfully.

Choosing the wrong model for the team and the store is the most consistent starting point for the failure patterns described in Why Headless Projects Fail.