WooCommerce is the world's most popular eCommerce platform, powering millions of stores. But its traditional PHP frontend can be sluggish, especially as product catalogues grow and plugins accumulate. Going headless — using WooCommerce as the backend engine while building a custom Next.js frontend — solves the performance problem while keeping the familiar WordPress admin. Here is how to set it up.
Architecture Overview
In a headless WooCommerce setup, WordPress and WooCommerce handle products, orders, customers, taxes, and shipping on the backend. The Next.js frontend fetches product data through the WooCommerce REST API or WPGraphQL with the WooGraphQL extension, renders pages with full control over the HTML and CSS, and manages the cart and checkout flow. The two applications run independently — WordPress on a server optimised for PHP, and the Next.js frontend on Vercel, Netlify, or any Node.js hosting platform.
The API choice matters. The WooCommerce REST API is stable and well-documented but requires multiple requests for complex pages. WPGraphQL with WooGraphQL allows you to fetch products, categories, variations, and reviews in a single request, which reduces frontend complexity and improves performance.
Setting Up the WooCommerce Backend
- Install and configure WooCommerce: Set up products, shipping zones, tax rates, and payment gateways as normal. The backend configuration is identical to a traditional WooCommerce store.
- Generate API credentials: In WooCommerce settings, create REST API keys with read/write access. Store these securely in environment variables — never commit API keys to version control.
- Install WPGraphQL and WooGraphQL: If using GraphQL, install both plugins and verify the GraphQL IDE works at your-site.com/graphql. Test queries for products, categories, and orders before starting frontend development.
- Disable the frontend theme: Redirect all public-facing WordPress URLs to your Next.js frontend. Keep the admin accessible at /wp-admin for content management.
Building the Next.js Frontend
Start with a Next.js App Router project. Create API utility functions that wrap WooCommerce API calls — getProducts, getProduct, getCategories, and so on. Use Next.js server components to fetch product data at build time or on request. Product listing pages can use static generation with revalidation (ISR) to balance performance with freshness. Product detail pages should also be statically generated for the best possible load times.
The cart is where headless WooCommerce gets complex. WooCommerce's cart is session-based on the server, which does not map well to a decoupled frontend. The most common approach is managing the cart client-side in React state or localStorage, then creating the WooCommerce order at checkout time. Alternatively, the WooCommerce Store API (part of WooCommerce Blocks) provides cart endpoints designed for headless use.
Handling Checkout and Payments
Checkout is the most critical and complex part of a headless WooCommerce build. You need to collect shipping and billing information, calculate taxes and shipping costs through WooCommerce's API, process payment through a gateway, and create the order in WooCommerce. Stripe is the most headless-friendly payment gateway — its client-side SDKs integrate seamlessly with React. For European customers, ensure your checkout supports Strong Customer Authentication (SCA) as required by PSD2.
When Headless WooCommerce Makes Sense
This approach works well when you have an existing WooCommerce store with established products and workflows but need a faster frontend, when your team knows WordPress well and does not want to migrate to a different eCommerce platform, or when you need the same product data across web and mobile applications. It is not the right choice if you are starting from scratch — in that case, consider Shopify or MedusaJS which are designed for headless from the ground up. At Born Digital, we evaluate each client's situation individually and recommend the architecture that best fits their team, budget, and growth plans.