How to White Label a Headless WordPress Build

To white-label a headless WordPress build, agree the content model and choose WPGraphQL or the REST API. Then wire up preview and revalidation, and finish with hosting, SEO and a handover under your agency’s name.

Editors keep the WordPress admin, and visitors get a Next.js front end. Your client never meets the partner.

Headless WordPress for agencies works best when each of these steps is written into the scope. Each one hides a decision your client will notice after launch.

What headless WordPress for agencies involves

WordPress stays where editors write and publish. A separate Next.js front end fetches that content and renders every page visitors see, so visitors never touch the WordPress install.

We know this setup from building it and from running on it. Before SoftVolt AI, our founder built The Bulk Bag Man, a site for a UK aggregates supplier, this way. Our own site, softvoltai.com, runs on headless WordPress with a Next.js App Router front end on Vercel.

The steps below follow the order we work in.

Step 1: Agree the content model

Decide what editors fill in before anyone writes a template. A headless front end only shows the fields you expose, so a missing field turns into a developer task later.

• One ACF field group per template, with the fields that template needs and nothing more.
• Custom post types for repeating content. The Bulk Bag Man exposes a Supplies post type.
• Menus and site settings exposed to the front end, because the header and footer depend on them.
• Only public data leaving WordPress, so drafts and private fields stay inside.
• A list of every plugin, with a note on whether it still works headless.

That last point catches agencies out. Plugins that output front-end HTML, such as page builders and sliders, stop working. Plugins that work on data, such as ACF and SEO plugins that store metadata, keep working.

We list each plugin in the scope and say what replaces it. You can then explain the change to your client before they find it.

Step 2: Choose WPGraphQL or the REST API

Both work, and we have used both. The right choice depends on how much each page asks for at once.

The WordPress REST API comes with WordPress. It sends and receives data as JSON, and any language that can make HTTP requests can use it. Each endpoint returns a set shape, so a busy page may need several requests.

WPGraphQL is a free, open-source plugin that adds a GraphQL API to WordPress. Its introduction to GraphQL explains that you ask for exactly the fields you want, and one request can replace many round trips.

Question	REST API	WPGraphQL
Extra plugin to maintain?	No, it comes with WordPress	Yes, one more plugin to update and test
Data per request	A set shape per endpoint	Exactly the fields the query asks for
Draft previews	A custom route you write and control	Supported, for requests authenticated as an editor
Where it fits best	Smaller sites with a few templates	Sites with many templates and related content

The Bulk Bag Man uses the REST API. A WordPress child theme exposes its ACF fields, menus and the Supplies post type. A Next.js App Router front end renders them on Vercel.

Our own site has more than a dozen content types, from services to case studies, and reads them all through WPGraphQL.

Plan forms at the same time. On The Bulk Bag Man, contact form submissions go through a Next.js route handler, so the browser never talks to WordPress directly.

Step 3: Make preview work for editors

Editors expect the Preview button to show their draft on the real site. In a headless build, that needs deliberate work on both sides.

On the Next.js side, Draft Mode handles it. WordPress opens a route handler with a shared secret, and the handler sets a Draft Mode cookie and redirects to the page. That browser then skips the cache, while other visitors still see the cached page.

On the WordPress side, something has to return the draft. WPGraphQL previews need the request to be authenticated as a user who can edit the post.

On softvoltai.com we took a different route. A read-only REST endpoint takes the shared secret and a post ID and returns that one post, including the newest autosave. The front end never holds a login that can write.

Test preview with a real editor before launch. Ask them to change a draft, preview it, publish it and check the live page. If any of those steps confuses them, fix it before your client sees it.

Step 4: Revalidate on publish

A headless front end serves cached pages, so the live site changes only when something tells Next.js to refresh. Get this wrong and your client publishes a price change that does not appear.

The Next.js revalidation docs describe two on-demand tools. revalidatePath drops one route, and revalidateTag drops every cached entry with a given tag. The docs prefer tags where possible, because they are more precise.

On our own site, a publish runs like this:

1. An editor saves, publishes or deletes a post in WordPress.
2. A small plugin works out which front-end paths and cache tags that post affects.
3. The plugin posts them to a Next.js route handler, with a shared secret in the header.
4. The route handler checks the secret and drops exactly those paths and tags.
5. The next visitor gets the new page, and every other page stays cached.

One detail matters. The docs recommend a profile for revalidateTag that keeps serving the old page while the new one builds. We expire the tag at once on publish instead, because editors check their change straight away.

Menu and settings changes refresh every page, since the header and footer appear everywhere. An admin bar button also rebuilds the whole front end for the rare page that looks stale.

Step 5: Decide hosting and account ownership

A headless build has two hosts. The Next.js front end runs on Vercel by default, or on the client’s own infrastructure. WordPress stays on its existing host, or moves to a new one, and stops serving visitors directly.

Put both accounts in your agency’s name or the client’s from day one. We bill hosting at cost or set it up in your account with no mark-up. Nothing depends on an account we keep.

Lock the CMS domain down as well. On our install, visitors to the WordPress domain go to the real site instead. The domain stays out of search indexes, while the admin, the APIs and previews keep working.

Step 6: Cover the SEO basics

A headless site can rank as well as any other, provided the rebuild carries the SEO work across. Next.js renders pages on the server, so search engines receive complete HTML. The rest is a checklist:

• A title, description and canonical tag for every route, drawn from the WordPress fields.
• An XML sitemap built from the published content.
• Structured data, validated before launch.
• A redirect from every old URL that changes.
• The WordPress domain kept out of the index, so the same content never appears on two hosts.
• Staging protected by a password and set to noindex.

We do not promise rankings. A clean technical base removes the problems that hold a rebuilt site back, and the rest depends on content and links.

Step 7: Hand over under your agency’s brand

Handover is where white label holds or fails. Your client may open the repository, the theme files or the hosting dashboard, and each one should show your agency or nobody.

• Commit messages, staging domains and documents carry your brand from the first day.
• Theme and plugin headers name your agency, with no footer credit or “built by” line.
• An editing guide in your brand shows where each WordPress field appears on the site.
• The Git repository transfers to you or the client, along with hosting and CMS access.
• A runbook documents any deployment on the client’s own infrastructure.
• Our access is revoked, and we confirm the removal in writing.

We sign a mutual NDA before the brief and never contact your client. Credentials live in a shared vault with least-privilege access, and our security page sets out each practice.

Where to start

Headless builds are included from our Growth plan, from £1,200 a month. It covers up to 3 active projects and up to 10 pages per project, and larger rebuilds get their own fixed-price scope.

Our headless WordPress development service covers this pattern. If the client needs a different CMS, such as Payload or Sanity, see white-label Next.js development.

Send us the brief with the current site URL and the client’s plugin list. You will get a written scope with a fixed price within two business days.