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.
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; we publish the timeline, not the price.
The four phases, in real time
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.
What stretches the timeline
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.
What compresses the timeline
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.
When the six-week answer is wrong
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.
When the sixteen-week answer is wrong
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.
What pricing looks like
Pricing is individual per project. We 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).
We 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.
Cluster reading
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.
