How long does a headless WordPress migration take in 2026
Six to sixteen weeks for typical engagements. The shape is four phases: discovery, scoping, build and cutover, tuning. The variables that stretch or compress the schedule are catalogue size, integration count, URL preservation, and editorial team readiness, not the framework choice. Every week range in this article is an estimate from my own delivery practice, not a market survey; the binding schedule is set after discovery.
This article anchors to the Headless WordPress service pillar and pairs with the Next.js vs Astro decision matrix for the framework angle and the Cloudflare Workers and WordPress at the edge article for the runtime layer.
TL;DR
- Editorial-only sites under fifty pages: four to six weeks.
- WooCommerce up to a few thousand SKUs with standard integrations: ten to fourteen weeks.
- Multi-region or multi-language with custom integrations: fourteen to sixteen weeks, sometimes longer.
- The expensive weeks are scoping (week one to two) and cutover (the final weekend), not the build itself.
- Pricing on the engagement is individual per project; I publish the timeline, not the price.
What are the phases of a headless WordPress migration
The phases are not labels on a Gantt chart; they map to distinct work modes that need different people in the room.
Phase 1, discovery (week zero to two)
Stakeholders, the editorial team, the analytics owner, and the technical contact sit through three to five sessions over one to two weeks. The deliverables are a content-model audit, a performance baseline taken from the live site (TTFB, TTI, LCP per template), a plugin and integration inventory, and a draft SEO migration map.
The output of discovery is decision input, not architecture. The team that skips discovery to “save time” buys back the cost in week eight, when an undeclared integration surfaces and the data layer needs a redesign.
Phase 2, scoping (week two to three)
Architecture decision: Astro 5+ or Next.js 15, per-route rendering choice, data fetching pattern (REST or GraphQL), cache invalidation strategy. The redirect map is signed off here, not later. The editorial workflow is finalised: previews, drafts, scheduled publishing, multi-author flows.
Scoping ends with a written engagement letter and a fixed deliverable list. Anything missing here will be a change order in week ten, which is the most expensive time to negotiate scope.
Phase 3, build and cutover (week three to twelve)
The build runs in two-week sprints with a weekly demo. Each demo is on staging, not localhost, so the team can see what the editorial side actually looks like in the new stack. The first sprint is the design system and a single template end to end; the next sprints fan out by template type.
The cutover itself is a forty-eight to seventy-two hour window, scheduled deliberately. Two patterns work: DNS swap (cleaner, slower to roll back) and reverse-proxy cutover (faster to roll back, more moving parts). The redirect map is applied at the edge, not in PHP.
The side-by-side measurement window runs for one to two weeks before cutover. It catches regressions in tracking tags, schema validation, and Core Web Vitals before they ship.
Phase 4, tuning and retainer (week twelve to sixteen)
Edge cache TTLs are tuned per route. Observability (Cloudflare Logpush, synthetic tests, alerting on TTFB and 5xx rates) is wired in. The retainer hand-off covers new feature work, quarterly Tech Radar reviews, and a roadmap for the editorial team’s evolving needs.
This is the phase that is most often skipped. Skipping it costs six months of low-grade incidents that the team cannot diagnose because nothing is instrumented.
Why a headless WordPress migration takes longer
Three patterns push a six-week project to twelve, and a twelve-week project to twenty.
Late discovery of integrations. A custom payment gateway, a legacy ERP integration over SOAP, a niche plugin with no REST surface. Each one adds a bespoke adapter. Each adapter adds two to four weeks of build, plus contract negotiation if a third party owns the upstream system.
URL preservation. A site with thirty unique URL patterns is mechanical. A site with three hundred patterns plus a permalink restructure is a project on its own. The 301 map is signed off in scoping, not improvised in week ten.
Content model rework. When the existing WordPress content is structured around theme templates instead of structured fields, the front end cannot consume it deterministically. Rebuilding the content model adds two to six weeks and requires editorial-team availability that most teams underestimate.
How to speed up a headless WordPress migration
Four conditions consistently shorten the schedule.
A clean content model. Custom post types, ACF or Meta Box field groups, or a recent move to the block editor with structured patterns. The front end reads structured data and renders deterministically. Saves two to four weeks.
Pre-existing design system. A figma library, a token set, or a component library the team has used before. Saves one to two weeks of foundation work in the first sprint.
Editorial team availability. When the editorial team can sit through previews weekly and sign off on flows, the build does not stall waiting for clarification. Saves one to two weeks across the engagement.
Senior team on both sides. A senior product owner on the client side reduces the question-and-answer cycle by half. The agency cannot manufacture this; it has to come from the buyer.
What to check before a headless WordPress migration
An estimate without an inventory is a guess. The list below can be worked through in the admin panel and the database in one working day, before anyone names a date. Each item is a place where a classic theme did something for free and a headless build has to rebuild it.
Content types and taxonomies. How many custom post types and taxonomies exist, and which of them have their own archives under URLs that are in the index. Every type with an archive is a separate template and a separate route on the front end.
ACF fields and meta. Field groups, repeaters, flexible content, relationship fields. Check whether they are exposed in the REST API (show_in_rest) or in the WPGraphQL schema. Flexible content with a dozen layouts means a dozen components to build.
Shortcodes and plugin blocks. Content stored in the database as a shortcode reaches the front end as raw text in square brackets. Count the occurrences with a query on post_content before deciding whether to render them or rewrite them.
Preview and drafts. A classic theme has preview out of the box. In headless it has to be built: an authenticated request for the draft and a preview mode on the front end. The editorial team notices it is missing in the first week. For authenticated REST requests, WordPress has offered application passwords since version 5.6: they work over HTTP Basic, are enabled by default only on sites served over HTTPS, and cannot be used to log into wp-admin (application passwords integration guide).
Forms. Contact Form 7 or Gravity Forms render inside the PHP theme. Once the theme is cut off, a form needs an endpoint, validation, spam protection and the GDPR consent wording the plugin used to add.
Search. The built-in ?s= disappears together with the theme. The options are a REST search endpoint, an external index or a static index generated at build time. Each option carries a different maintenance cost.
Market-specific checkout integrations. Local payment gateway plugins, parcel locker pickers at checkout, order export to invoicing tools. These plugins are written for a checkout that WooCommerce renders, so in a headless build they have to be verified against the provider’s API, not against the plugin’s PHP code. These are the integrations that surface too late in the section on what stretches the timeline.
Redirects. An export from the Redirection plugin or from .htaccess rules, plus the URL lists from the sitemap and Google Search Console. This becomes the 301 map that the scoping phase signs off.
The result is a table with three columns: the item, where it lives today, who rebuilds it. Rows without an owner are weeks the schedule does not contain yet.
How long a headless WooCommerce migration takes
A WooCommerce store with three thousand SKUs and a custom checkout will not migrate in six weeks. Anybody quoting that timeline is selling a different scope and renegotiating later. The honest answer for that profile is twelve to fourteen weeks.
A multi-region site with five locales and locale-specific commerce flows is not a six-week project either. Translation workflows, hreflang validation, locale-specific cache strategies, and per-region payment integrations add four to six weeks even on top of a healthy baseline.
How long does a small headless WordPress site take
A small editorial site, a freshly built WordPress install, a clean content model, and a senior team can ship in five weeks. Quoting sixteen for that profile is padded scope.
A greenfield headless site (no migration component, just a new front end on a new WordPress) skips most of phase one and shortens phase three. Six to eight weeks total.
How much a headless WordPress migration costs
Pricing is individual per project. I do not publish service prices on the public site. The engagement letter ties hours to the four phases above, with a fixed cap on phase one (it is bounded by interview count, not by anything that scales) and time-and-materials or fixed-scope on phase three (depending on how stable the scope is after scoping).
I bill in EUR or USD, EU jurisdiction, B2B contract. See the Headless WordPress service pillar for the engagement model and the About WPPoland page for the team and the EU jurisdiction default.
How to estimate a headless migration timeline yourself
The variables that decide the length of the project can be checked before anyone prepares a quote. They move a project between six and sixteen weeks; the framework makes a difference of a week at most.
- Catalogue. Count the editorial pages and SKUs. A site under fifty pages without a shop is a different profile from WooCommerce with a few thousand products.
- Integrations. List everything that exchanges data with WordPress: ERP, payment gateway, plugins without a REST surface. Each item discovered only during the build means a separate adapter.
- URL patterns. Export the list of addresses and group them by structure. Thirty patterns is mechanical work; three hundred with a permalink restructure is a project of its own.
- Content model. Check whether content lives in custom post types and ACF or Meta Box fields, or is spread across theme templates.
- Editorial team. Name the person on your side who will approve previews regularly and answer the team’s questions.
With this list, the first discovery sessions go into verifying data you already have, and it is quicker to see which TL;DR profile your site fits.
How to expose post types and fields in the REST API and WPGraphQL
The ACF item on the checklist has a concrete technical cause. A custom post type does not appear in the REST API until it is registered with show_in_rest => true. That argument adds a route in the wp/v2 namespace, and the URL segment defaults to the post type name unless rest_base is set (WordPress REST API handbook). Taxonomies need the same argument in register_taxonomy.
WPGraphQL has its own switch. A post type enters the GraphQL schema once show_in_graphql and graphql_single_name (camel case, no spaces, starting with a letter) are set. graphql_plural_name is optional; without it the list field gets the all prefix (WPGraphQL documentation). The same documentation describes a trap typical of headless builds: anonymous requests return published entries only when public or publicly_queryable is true. A type registered as non-public because the theme has no template for it returns data only to users who can edit it. The documentation recommends setting publicly_queryable => true explicitly in that case.
So the discovery inventory should record three values for every post type: show_in_rest, show_in_graphql and publicly_queryable. A missing one is a change in the registration code, not in the front end.
How to prepare a 301 redirect map for a headless migration
Google treats a change of URLs as a site move and recommends server-side permanent redirects (301 or 308) from every old URL to its counterpart, following a mapping prepared before the move. The same documentation warns against sending many old URLs to one irrelevant page such as the homepage. Redirects should stay in place as long as possible, generally at least one year. For medium-sized sites Google can take a few weeks or more to show the new URLs instead of the old ones, and visibility in Search may fluctuate during that time (Google Search Central on site moves with URL changes).
When the map is applied at the edge, the platform limit matters. The _redirects file on Cloudflare Pages accepts up to 2,000 static and 100 dynamic redirects, 2,100 in total, and each rule has a 1,000-character limit. Larger maps go to Bulk Redirects (Cloudflare Pages documentation). That is why the URL pattern count from discovery shapes the architecture: thirty patterns fit as dynamic rules within the limit, while thousands of individual URLs with no shared pattern need a different mechanism.
SSG, ISR or SSR and how rendering affects publishing
Scoping chooses rendering per route, and that choice decides when a change saved in the WordPress admin appears on the site. Astro prerenders pages, routes and endpoints at build time by default. A single page switches to on-demand rendering with export const prerender = false, and output: 'server' flips the default for the whole project. Both need a server adapter (Astro documentation). In a purely static setup every publication means a new build, so the editorial workflow needs a build trigger after a post is saved.
Next.js has Incremental Static Regeneration. The revalidate export sets the time after which the next request starts regenerating the page in the background, and revalidatePath and revalidateTag invalidate the cache on demand, for example from a webhook fired on publish. The documentation lists the limits: ISR does not work with a static export, adapter support is platform-specific, and with several instances the default cache is per instance, so an on-demand invalidation reaches only the instance that received the call unless a shared cache handler is configured (Next.js ISR guide).
This is why preview and scheduled publishing are settled in the scoping phase together with rendering, not at the end of the build.
Related articles
The supporting articles in this cluster, by topic.
- Headless WordPress: ISR vs SSR rendering decision on per-route rendering choice in scoping.
- SEO patterns for headless WordPress on the redirect map and canonical strategy.
- Cloudflare Workers and WordPress at the edge on the runtime layer of the new stack.
- Economics of headless WordPress 2026 on the five-year TCO that justifies the engagement.
- Headless WordPress for WooCommerce on the catalogue-size decision rule.
