WooCommerce REST API vs WPGraphQL: Which Is Better for Headless Stores?

If you're building a headless WooCommerce store, one of the first decisions you'll face is how your frontend talks to WordPress. The two serious options are the WooCommerce REST API (built into WordPress core and WooCommerce) and WPGraphQL (a community plugin that adds a full GraphQL server). Both work. Both are used in production. But they suit different projects, different teams, and different levels of complexity.

TL;DR

Use the WooCommerce REST API if you need reliable commerce operations (cart, checkout, orders, payments) — it's mature and battle-tested. Use WPGraphQL for content-heavy pages where you need flexible queries across posts, custom fields, and taxonomies. Many production headless stores use both: REST for commerce, GraphQL for content.

What each API actually does

Before comparing them, let's be precise about what we're talking about. These are fundamentally different approaches to exposing WordPress data.

The WooCommerce REST API

WordPress has shipped a REST API since version 4.7 (December 2016). WooCommerce extends it with dedicated endpoints for products, variations, categories, tags, attributes, orders, customers, coupons, shipping zones, tax classes, payment gateways, and more. Hit /wp-json/wc/v3/products and you get JSON. It follows standard RESTful conventions — GET, POST, PUT, DELETE — with pagination, filtering, and authentication via consumer keys or application passwords.

The WooCommerce REST API is maintained by Automattic (the company behind WordPress.com and WooCommerce). It's not a side project — it's the official interface for WooCommerce integrations, mobile apps, and third-party tools. Most WooCommerce SaaS products (inventory management, accounting, shipping) rely on it.

WPGraphQL

WPGraphQL is an open-source plugin that adds a GraphQL server to WordPress. Instead of hitting multiple REST endpoints, you write a single query that requests exactly the fields you need. For WooCommerce support, you also need the WPGraphQL WooCommerce (WooGraphQL) extension, which maps WooCommerce data types to the GraphQL schema.

WPGraphQL was created by Jason Bahl and is backed by WP Engine. It powers Faust.js and is used by agencies and enterprise WordPress projects. The core plugin has over 30,000 active installations and a strong community.

700+

REST API endpoints in a WooCommerce site

30k+

Active WPGraphQL installations

GraphQL endpoint for all queries

Head-to-head comparison

Let's compare these APIs across the dimensions that actually matter when building a headless WooCommerce store.

Data fetching efficiency

This is where the difference is most obvious. To build a product page with REST, you might need:

GET /wc/v3/products/123 — product data
GET /wc/v3/products/123/variations — variations
GET /wp/v2/media/456 — gallery images
GET /wc/v3/products/reviews?product=123 — reviews
GET /wc/v3/products?category=789 — related products

That's five round trips. With GraphQL, it's one query that returns exactly the fields you need from all of those resources. For content-heavy pages that pull from multiple post types, custom fields, and taxonomies, GraphQL's efficiency advantage compounds.

However, for simple operations — fetching a list of products with standard fields — the REST API is perfectly fine. The N+1 problem only hurts when you're assembling complex pages from multiple data sources.

Commerce operations

This is where the REST API pulls ahead significantly. Cart management, checkout flows, order creation, payment processing, coupon validation, shipping calculations, and tax handling — the WooCommerce REST API covers all of these with mature, well-documented endpoints.

WPGraphQL WooCommerce has made progress on mutations (write operations), but it's less mature. Cart session handling, payment gateway integration, and checkout flows are more complex to implement via GraphQL, and edge cases are less well-documented. Most production headless WooCommerce stores use the REST API for commerce operations, even if they use GraphQL for content.

The cart problem

WooCommerce cart sessions were designed for server-side PHP, not stateless API requests. Both REST and GraphQL require workarounds for persistent carts — storing cart tokens, managing session cookies, or using plugins like CoCart. This is a WooCommerce limitation, not an API limitation.

Caching

REST APIs are inherently cacheable. Each endpoint has a unique URL, responds to standard HTTP cache headers, and works with CDNs, edge caches, and browser caches out of the box. GET /wc/v3/products/123 can be cached at every layer.

GraphQL queries all hit a single endpoint (/graphql) via POST requests, which CDNs don't cache by default. You need application-level caching (Redis, in-memory, or a GraphQL-aware CDN like Stellate) to get comparable performance. It's solvable but requires more infrastructure.

WooCommerce REST API: pros and cons

Pros

Built into WordPress and WooCommerce — zero plugin dependencies
Complete commerce coverage: cart, checkout, orders, payments, shipping, tax
Familiar RESTful patterns with standard HTTP methods
Natively cacheable with HTTP cache headers and CDNs
Extensive documentation maintained by Automattic
Every WooCommerce integration and SaaS tool uses it
Stable API with versioning (v3) — breaking changes are rare

Cons

Over-fetching: endpoints return fixed data shapes with fields you may not need
Multiple requests needed for complex pages (N+1 problem)
No way to request nested resources in a single call
Limited filtering — you cannot query by arbitrary custom fields
Pagination can be inefficient for large catalogues

WPGraphQL: pros and cons

Pros

Request exactly the fields you need — no over-fetching
Single query for complex, nested data across multiple types
Strongly typed schema with introspection and IDE tooling
Excellent for content-heavy pages mixing posts, ACF fields, and taxonomies
Growing ecosystem of extensions for WordPress plugins
Built-in GraphiQL IDE for exploring and testing queries

Cons

Requires a plugin (WPGraphQL) plus a second plugin for WooCommerce (WooGraphQL)
Commerce mutations are less mature than REST API equivalents
Harder to cache — single POST endpoint defeats standard HTTP caching
Learning curve for teams unfamiliar with GraphQL
Less documentation for WooCommerce-specific operations
Plugin updates can introduce schema changes that break queries

When to use which (practical decision framework)

After working with both APIs on headless WooCommerce projects, here's the practical guidance.

Use the REST API when:

Your store is primarily commerce-focused (product catalogue, cart, checkout)
You want zero additional plugin dependencies
Your team is comfortable with REST and doesn't know GraphQL
You need reliable caching at the CDN/edge layer
You're integrating with third-party services that use REST

Use WPGraphQL when:

Your site is content-heavy with complex page layouts pulling from multiple sources
You use Advanced Custom Fields extensively and need flexible queries
Your team already knows GraphQL from other projects
You want to minimise API round-trips for page performance
You're building a content site with light commerce (blog + shop)

Use both when:

You need rich content querying AND reliable commerce operations
Your product pages mix WooCommerce data with custom ACF content
You want the best tool for each job rather than compromising on one

The pragmatic approach

Most production headless WooCommerce stores we've seen use both APIs. GraphQL for content pages and product information, REST for cart, checkout, and order management. This isn't a compromise — it's using the right tool for each job. Our WordPress as headless CMS guide covers this hybrid approach in detail.

How WPBundle approaches this

WPBundle uses the WooCommerce REST API as its primary data layer for commerce operations. Cart management, checkout, orders, payment processing, and catalogue queries all go through the REST API — with a companion WordPress plugin that extends the default endpoints to fill gaps WooCommerce doesn't cover out of the box (things like optimised product queries, session management, and storefront configuration).

WooCommerce REST API for all commerce operations
Extended API endpoints via companion WordPress plugin
Server-side caching layer for API responses
Persistent cart sessions without third-party plugins
Optimised product queries for catalogue and search pages
Works alongside WPGraphQL if you need content queries

The REST API versus WPGraphQL debate matters most when you're building from scratch. With WPBundle, the commerce layer is already wired up — you don't need to make these low-level API decisions yourself. If you want to learn more about the architecture choices behind headless WooCommerce, see our guide on what is headless WooCommerce or the broader headless WordPress guide.

Making your decision

The WooCommerce REST API vs WPGraphQL decision is not about which is "better" in the abstract. It's about which fits your project. For pure commerce, the REST API is more mature and reliable. For content-rich sites, WPGraphQL is more flexible and efficient. For most real-world headless WooCommerce stores, the answer is both — and that's perfectly fine.

What matters more than the API choice is the implementation. Whichever you choose, you still need to handle cart sessions, build a checkout flow, implement SEO, and optimise performance. Those are the hard parts of headless WooCommerce — and they're the parts that WPBundle handles for you. The API layer is just plumbing. The storefront is where the value lives.