← Back to Guides

WordPress as a Headless CMS: A Practical Guide

WPBundle Team··10 min read
wordpress as headless cmswordpress headless cmswordpress as a headless cmsheadless wordpress

WordPress powers over 43% of all websites on the internet. That install base is staggering — and it means millions of teams already have content, workflows, and expertise built around the WordPress admin. What many don't realise is that WordPress has shipped a full REST API since version 4.7, making it a genuinely capable option if you want to use WordPress as a headless CMS. You don't need to migrate to Contentful or Sanity to go headless. You might already be sitting on the right tool.

TL;DR

Headless WordPress means keeping the WordPress admin for content management while serving your frontend with a modern framework like Next.js or Nuxt. The built-in REST API and the WPGraphQL plugin give you two solid ways to query content. It's a particularly strong choice when you already have WordPress content or run WooCommerce — and WPBundle makes the e-commerce side production-ready out of the box.

What "headless WordPress" actually means

In a traditional WordPress setup, PHP handles everything: storing content in MySQL, applying your theme's templates, and rendering the final HTML that reaches the browser. The backend and frontend are a single, tightly coupled application.

A headless WordPress architecture breaks that coupling. WordPress continues to manage your content — posts, pages, custom post types, media, users — but it no longer renders the frontend. Instead, a separate application (built with React, Next.js, Vue, Nuxt, Astro, or any framework) fetches content from WordPress via its API and handles all presentation.

The WordPress admin stays exactly the same. Your editors log in, write content, manage media, and publish — all through the familiar dashboard. The only difference is what happens after they hit "Publish." Instead of PHP generating a page, your frontend application pulls that content through an API and renders it however you choose.

The key distinction

"Headless" doesn't mean removing WordPress. It means removing the WordPress theme layer. WordPress becomes a content backend — and a very good one, given two decades of refinement.

How WordPress works as a headless CMS

WordPress offers two main approaches for exposing content to external frontends: the built-in REST API and the WPGraphQL plugin. Both are mature, well-documented, and used in production by major organisations.

WordPress The WordPress REST API

Since WordPress 4.7 (released December 2016), every WordPress installation ships with a complete REST API. No plugins required. Hit /wp-json/wp/v2/posts and you get JSON. It covers posts, pages, categories, tags, media, users, comments, and custom post types. It supports filtering, pagination, embedding related resources, and authentication via application passwords, JWT, or OAuth.

The REST API is battle-tested. The WordPress.com editor (Calypso), the Gutenberg block editor, and thousands of mobile apps rely on it daily. It's not experimental — it's core infrastructure.

GraphQL WPGraphQL

WPGraphQL is a free, open-source plugin that adds a full GraphQL server to WordPress. Instead of multiple REST endpoints, you write a single query that asks for exactly the fields you need. This is particularly useful for complex pages that pull from posts, custom fields (ACF), menus, and settings simultaneously — one request instead of five.

WPGraphQL has strong ecosystem support. Extensions exist for Advanced Custom Fields, WooCommerce, Yoast SEO, Gravity Forms, and most major plugins. It's the backbone of frameworks like Faust.js (formerly Headless WP by WP Engine).

8+ years

WordPress REST API in core

30k+

Active WPGraphQL installations

700+

REST API endpoints in a typical WooCommerce site

REST API vs WPGraphQL: which to choose

Both approaches work well for using WordPress as a headless CMS, but they suit different scenarios. Here's an honest comparison.

WordPress WordPress REST API

Pros

  • Built into WordPress core — zero plugin dependencies
  • Familiar RESTful patterns that any backend developer understands
  • Extensive documentation and community resources
  • WooCommerce REST API is mature and covers all commerce endpoints
  • Simple to cache with standard HTTP caching headers

Cons

  • Over-fetching: endpoints return fixed data shapes, often more than you need
  • Multiple requests needed for complex pages (N+1 problem)
  • No built-in way to request nested or related resources in one call
  • Filtering and querying options are limited compared to GraphQL

GraphQL WPGraphQL

Pros

  • Request exactly the fields you need — no over-fetching
  • Single request for complex, nested data (posts + author + categories + ACF fields)
  • Strongly typed schema with built-in introspection
  • Excellent developer tooling (GraphiQL IDE built in)
  • Extensions for ACF, WooCommerce, Yoast, and more

Cons

  • Requires a plugin — adds a dependency to manage and update
  • Harder to cache than REST (all queries hit a single endpoint via POST)
  • Learning curve if your team is unfamiliar with GraphQL
  • Some edge-case WordPress features lack GraphQL coverage
  • WooCommerce support (via WPGraphQL WooCommerce) is less mature than the REST API

Practical advice

If you're building a content-heavy site (blog, magazine, marketing pages), WPGraphQL is often the better choice — the query flexibility saves significant frontend complexity. For e-commerce with WooCommerce, the REST API is more mature and better documented. You can also use both: GraphQL for content, REST for commerce.

WordPress vs dedicated headless CMS platforms

If you're evaluating WordPress as a headless CMS, you're probably also looking at purpose-built alternatives like Contentful, Sanity, and Strapi. Each has genuine strengths. The right choice depends on your team, your existing content, and your budget.

WordPress (headless) vs Contentful

Contentful is a cloud-hosted, API-first CMS with a polished content modelling interface. It's excellent for structured content at scale. However, it charges per user and by API calls, which adds up quickly. WordPress is free, self-hosted, and already has your content if you're migrating from a traditional WordPress site.

WordPress (headless) vs Sanity

Sanity offers real-time collaboration, a customisable editing studio, and GROQ (its own query language). It's developer-friendly and flexible. The trade-off is that you're building your content model from scratch, and Sanity's free tier has usage limits. If your editors already know WordPress, the retraining cost is zero with headless WordPress.

WordPress (headless) vs Strapi

Strapi is an open-source, self-hosted headless CMS built with Node.js. It's a strong choice for teams that want full control without vendor lock-in. But Strapi's plugin ecosystem is a fraction of WordPress's, and it has no built-in e-commerce equivalent to WooCommerce.

Pros

  • Free and open source — no per-seat or API-call pricing
  • Your editors already know the WordPress admin
  • Massive plugin ecosystem (60,000+) for extending functionality
  • WooCommerce gives you full e-commerce built in
  • Existing content stays exactly where it is — no migration needed
  • Two decades of security patches, performance improvements, and battle-testing

Cons

  • WordPress admin UI is less modern than Contentful or Sanity
  • Requires hosting and maintenance (unless using managed WordPress)
  • Content modelling is less flexible than purpose-built headless CMS tools
  • PHP dependency for the backend, even though the frontend is decoupled
  • Some REST API responses are verbose and require filtering

The honest take

If you're starting from scratch with no existing content, no WordPress expertise, and no e-commerce requirements, a dedicated headless CMS like Sanity or Contentful may be the cleaner choice. But if you already have WordPress content, a team that knows the admin, or WooCommerce products — headless WordPress avoids a costly migration and keeps what already works.

Benefits of headless WordPress

The case for using WordPress as your headless backend is strongest when you consider the full picture — not just the API, but everything that surrounds it.

  • Familiar admin interface that editors and content teams already know
  • The largest CMS plugin ecosystem in the world (SEO, forms, analytics, multilingual)
  • Free and open source with no per-user or API-call pricing
  • Proven at scale — The New York Times, TechCrunch, and BBC America use WordPress
  • Gutenberg block editor gives structured content creation out of the box
  • Built-in user roles and permissions for editorial workflows
  • Extensive hosting options from $5/month shared to enterprise managed
  • WooCommerce turns it into a full e-commerce backend with payments, shipping, and tax

The "familiar admin" point deserves emphasis. Migrating a content team to a new CMS is expensive and disruptive. With headless WordPress, your editors change nothing about how they work. The transformation is entirely on the frontend — invisible to the people writing content.

Challenges you should know about

Headless WordPress is not without trade-offs. Being honest about these upfront will save you from unpleasant surprises mid-project.

Security surface area

Exposing WordPress via API means your WordPress installation is still publicly accessible. You need to lock down the admin, keep WordPress and plugins updated, use application passwords or JWT rather than cookie authentication, and ideally restrict API access by IP or authentication where possible. The attack surface doesn't shrink just because you removed the theme.

Hosting complexity

You now have two applications to host and maintain: WordPress (PHP, MySQL) and your frontend (Node.js or static hosting). This means two deployment pipelines, two sets of environment variables, and two things that can go down independently. Managed WordPress hosts like WP Engine or Kinsta handle the WordPress side, while Vercel or Netlify handle the frontend.

Performance tuning

The WordPress REST API is not fast by default. Without caching, each API request hits PHP and MySQL. You'll want object caching (Redis or Memcached), a persistent cache plugin, and ideally a CDN or edge cache in front of your API responses. WPGraphQL can be slower than REST for simple queries due to the overhead of parsing GraphQL.

No built-in preview

In a traditional WordPress site, clicking "Preview" shows you exactly what the published page will look like. In a headless setup, preview requires custom integration — your frontend needs a draft mode that fetches unpublished content from WordPress. Frameworks like Next.js support draft mode, but wiring it up is additional work.

Don't underestimate these

Every one of these challenges is solvable. But they each take time and expertise. Budget for them in your project plan, especially preview integration and API performance — these are the two that most often catch teams off guard.

WooCommerce Headless WordPress for e-commerce

This is where headless WordPress gets particularly interesting. WooCommerce is the most popular e-commerce platform in the world, powering over 5 million stores. Its REST API covers products, variations, orders, customers, coupons, shipping zones, tax classes, and payment gateways. If you're already running WooCommerce, going headless means keeping all your product data, order history, and payment integrations intact while dramatically improving the shopping experience.

A headless WooCommerce storefront built with Next.js can deliver sub-second page loads through static generation, offer app-like interactions with client-side routing, and provide the kind of polished checkout experience that customers expect from modern e-commerce brands. The performance gains translate directly into higher conversion rates.

5M+

Active WooCommerce stores worldwide

2-5x

Faster page loads with a headless frontend

1%

Conversion lift per 100ms of speed improvement

The hard parts of headless WooCommerce

The WooCommerce REST API is comprehensive but it wasn't designed for building storefronts. Cart management, session handling, checkout flows, real-time pricing, and payment gateway integration all require significant custom work. Most teams underestimate this by months.

This is exactly the problem WPBundle solves. WPBundle is a production-ready headless WooCommerce starter kit built on Next.js. It includes persistent cart sessions, a complete checkout flow with shipping and tax calculations, automatic SEO with structured data, a companion WordPress plugin that extends the REST API, and a full component library for product pages, search, and filtering.

  • Persistent cart with WooCommerce server-side sync
  • Complete checkout — shipping, taxes, coupons, payment processing
  • Automatic SEO with meta tags, JSON-LD, and sitemaps
  • Product catalogue with search, filtering, and sorting
  • AI-powered catalogue tools for descriptions and metadata
  • Works with your existing WooCommerce payment gateways
  • Companion WordPress plugin with extended API endpoints
  • Migration toolkit to run headless alongside your existing theme

Getting started with headless WordPress

If you're ready to use WordPress as a headless CMS, here are the practical steps to get moving.

1. Audit your current WordPress setup

List every plugin you rely on and check whether it exposes data via the REST API or has a WPGraphQL extension. Plugins that only modify the PHP frontend (visual builders, theme-dependent widgets) will need alternatives. Content-focused plugins (ACF, Yoast, WPML) typically work well in headless setups.

2. Choose your API approach

For content sites, install WPGraphQL and use the built-in GraphiQL IDE to explore your schema. For WooCommerce stores, start with the REST API — it has the most complete commerce coverage. You can use both in the same project.

3. Pick your frontend framework

Next.js is the most popular choice for headless WordPress due to its support for static generation, server-side rendering, incremental static regeneration, and API routes. Nuxt (Vue), Astro, and Remix are also viable depending on your team's expertise.

4. Set up authentication

For read-only public content, no authentication is needed — the REST API serves published content openly. For authenticated operations (creating orders, managing users), use WordPress application passwords (built in since 5.6) or JWT tokens. Lock down the WordPress admin with two-factor authentication and IP restrictions.

5. Handle preview and drafts

Set up Next.js draft mode (or your framework's equivalent) to let editors preview unpublished content. This typically involves a secret token passed from WordPress to your frontend that triggers server-side rendering of draft posts.

For WooCommerce stores

Skip the months of custom development. WPBundle gives you a production-ready headless WooCommerce frontend with cart, checkout, SEO, and catalogue management built in. Join the waitlist to get free beta access.

When to use WordPress as a headless CMS (and when not to)

After working with headless WordPress across dozens of projects, here is a practical decision framework.

Use headless WordPress when:

  • You already have content in WordPress and don't want to migrate
  • Your content team knows and likes the WordPress admin
  • You run WooCommerce and want a faster storefront
  • You need a plugin that only exists in the WordPress ecosystem
  • Budget matters — WordPress is free, and hosting is cheap
  • You want proven technology that scales from blogs to enterprise

Consider alternatives when:

  • You're starting from zero with no existing WordPress content
  • Your content model is highly structured and relational (Sanity or Contentful may be better)
  • You need real-time collaborative editing (Sanity excels here)
  • You don't want to manage PHP/MySQL hosting at all
  • Your team has zero WordPress experience and no reason to learn it

The WordPress headless CMS approach is not the right answer for every project. But it is a legitimate, battle-tested option that deserves serious consideration — especially when your content already lives in WordPress or you need WooCommerce's e-commerce capabilities. The REST API is mature. WPGraphQL is production-ready. The ecosystem is unmatched. And with tools like WPBundle handling the hard parts of headless WooCommerce, the barrier to entry has never been lower.

Ready to go headless?

Join the WPBundle waitlist and get beta access completely free.

Join the Waitlist