migration / seo

Headless CMS Migration: A Buyer's Guide for Marketing Teams

Written for the person who has to justify the project internally: what the work covers, what to ask an agency, what a fixed scope looks like, and the risk that sits in the redirect map.

A headless migration replaces the machinery underneath your website while the site stays open for business, and it goes far deeper than a redesign with a fresh coat of paint. The pages your visitors see might look similar on launch day. What changes is everything behind them: where content lives, how it is structured, how it reaches the browser, and who can publish without filing a ticket.

That distinction matters because it explains both the upside and the risk. The upside is a marketing team that stops waiting on developers and a site that is fast by default. The risk is that you are moving every URL you have ever ranked for, and search engines do not forgive a sloppy move.

This is the complete picture of what a headless migration involves. Each section answers one question, and where a topic deserves its own deep dive, this post points you to it rather than repeating it.

What is a headless CMS migration?

A headless CMS migration moves a website off a traditional all-in-one platform, where content and presentation are welded together, onto a setup where the two are separate. The CMS becomes a content store that holds structured data. A separate frontend framework decides how that data becomes a page. The content survives the move, and in this, the common case, the presentation layer gets rebuilt. The same word covers a move between two headless platforms, where the content is already separate and the frontend can often stay.

In a traditional CMS like WordPress, Drupal, or TYPO3, the same system stores your content, renders the HTML, runs the plugins, and serves the page on every request. “Headless” means cutting the head off that body: the CMS keeps the content, and a framework like Astro or Next.js takes over rendering, usually producing static pages that a CDN serves directly. There is no PHP running per visit, no plugin chain to execute, no database query between a click and a page.

The split looks like this:

Aspect Traditional CMS Headless setup
Content and presentation Welded together in one system Separated: a content store plus a frontend
Rendering The CMS renders HTML on every request A framework like Astro or Next.js renders, usually as static pages
Serving PHP, plugins, and a database query per visit Static pages served directly from a CDN
Examples WordPress, Drupal, TYPO3 A frontend framework over a structured content store

The word “migration” is doing real work in that sentence. You are not starting fresh. You have a live site with history, rankings, and integrations, and all of it has to come across without breaking.

Why do companies migrate to headless?

Three reasons come up again and again:

  • The team is slowed down by the CMS, waiting on developers for routine updates.
  • The site is slow for visitors, and on a legacy stack that is structural rather than a tuning problem.
  • Managing more than one market has become painful, with multilingual work fighting the platform.

A headless setup addresses all three at the architecture level rather than patching around them. The trigger is usually a marketing team that has run out of patience with how long routine work takes.

The editor experience is the quiet one. Most legacy setups were built for developers rather than for the people publishing on them every day, and the team pays that cost in time. We wrote about how editor experience determines whether a site succeeds and the signs your CMS is holding the marketing team back. If routine updates need a developer, that is the signal.

Performance is the measurable one. 49.5 percent of WordPress origins pass Core Web Vitals on mobile, against 69.8 percent of Astro origins, on July 2026 field data from the HTTP Archive Technology Report. The median WordPress site ships 119 KB of CSS on mobile before a single image loads, measured in the July 2025 crawl behind the HTTP Archive Web Almanac 2025. The architecture permits that gap rather than guaranteeing it, and we covered what decides the outcome in Core Web Vitals after migration.

Then there is multi-market work. Running one site across several languages on a traditional CMS tends to mean either duplicated installs or a tangle of plugins. Structured content handles this cleanly, which is why managing multilingual content at scale is one of the most common reasons a scale-up makes the move. If you are weighing the move against staying put, the case for a headless alternative lays out the trade-offs. Vendor uncertainty is a fourth trigger worth considering: what the Salesforce acquisition means for Contentful customers is the recent case in point: Salesforce completed its purchase of Contentful in September 2026, and Contentful customers now renew with a new owner.

What actually changes when you go headless?

The biggest change is that you start modeling content instead of typing it into a page. Every page type gets broken into structured components, the frontend becomes its own codebase with a build and deploy step, and hosting moves to a CDN. Editors gain a system that gets out of their way. The organization takes on a frontend that needs developers to maintain it.

It would be dishonest to pretend this is free. A headless setup has more moving parts than a single WordPress install. There is a content model to design, a frontend to build, and a deployment pipeline to run. The payoff is that each piece does one job well, but someone has to own the frontend after launch. That is a real consideration, and it is why we treat the part after launch as the hard part rather than the build itself. If Astro is the frontend direction you are considering, what Astro 7 changes for a marketing site is worth reading before you commit.

For editors, the day-to-day gets simpler. Content lives in clean, reusable blocks. There is no design mode to fight, no theme settings to break, no plugin that conflicts with another plugin. For the business, the trade is a system that holds up for years against one that needs rebuilding every couple of years.

How does a headless migration actually work, step by step?

A migration done properly moves through discovery, content architecture, design, build, and a staged go-live, with the client approving the plan before any building starts:

  1. Discovery: crawl and understand what you are migrating from.
  2. Content architecture: define what content lives on each page.
  3. Design: work from the approved content model rather than ahead of it.
  4. Build: develop against the approved design.
  5. Staged go-live: prove the system on real content, then cut over page by page.

The single rule underneath it is that the right work happens in the right order. Design before content architecture, or development before approved design, is how projects get redone halfway through.

We run every migration through the Essential Launch Framework: six phases, three client decision gates, and a proxy migration model that lets pages move one at a time instead of forcing one high-stakes launch. Rather than repeat the whole framework here, that post walks through each phase and why it exists.

The short version: you cannot plan a migration without first crawling and understanding what you are migrating from, you cannot design without knowing what content lives on each page, and you cannot safely cut over without proving the system works on real content first. Skipping any of those just moves the cost to a worse moment, usually weeks after launch.

The starting point decides most of the work. WordPress is the most common one we are called in on, and the WordPress to headless path covers the plugin chain, the export gotchas, and the redirect patterns unique to it. Webflow moves have their own shape, from CMS Collections to URL preservation, covered on the Webflow to headless page.

How do you migrate to a headless CMS with minimal downtime?

A well-run cutover needs no downtime for visitors. The old site answers every URL until the new one has passed its checks, and the switch itself is a routing change that takes effect in seconds at a CDN edge, or inside your DNS record’s TTL. What stops is publishing. Editors hold off in the old CMS from the final content sync until the new site is live.

This section describes a single cut: one freeze, one switch, one rollback window.

On our own projects the same steps run page by page, because the Essential Launch Framework uses a proxy migration, where the old and the new system each serve part of the site behind one domain while pages move across.

Most of a twelve to eighteen week project runs alongside a live site. The old CMS keeps publishing, the old site keeps serving traffic, and the new frontend is built and filled on a temporary address that search engines are kept out of. The only window where anybody has to change how they work is the content freeze, and its length comes out of how much content changes per day and how long the verification pass takes. On our own projects the freeze and the final checks together come to about a day.

Timeline of a headless migration, discovery to the cut, 12 to 18 weeks. Discovery comes first, then content model and build, the bulk import overlapping the end of the build, the content freeze with verification inside it, then the cut. Visitors get the old site until the cut and the new site after it. Editors publish in the old CMS until the freeze, and in the new CMS from the cut onward
Most of the project runs alongside a live site. The cut itself takes minutes.
Stage What visitors get What the team can do
Content model and build The old site, unchanged Publish in the old CMS as normal
Bulk import The old site, unchanged Publish as normal. The import is a snapshot and the gap gets synced later
Content freeze The old site, unchanged Draft in either system. Publishing in the old CMS stops
Verification The old site, unchanged Sign off the checks, or call the cut off
The cut The new site Nothing. This part is minutes of work
Rollback window The new site, watched Publish in the new CMS, and keep a list of what has gone out since the cut

The freeze only has to carry what changed since the last import, which is why the bulk import runs before it. It goes through the new CMS’s write API, and those are rate limited: Storyblok documents 3 requests per second on its Starter plan and 6 on its paid plans. At 6 requests a second and one write per item, 10,000 items is 1,667 seconds of pure API time, about 28 minutes, before assets, retries, or any item that needs a second call. Import a live site at that pace and it has changed under you by the time you finish. Import it before the freeze and the freeze carries only what changed since the snapshot.

Check whether your CMS has a read-only or publishing-lock mode. Where there is none, the freeze is held by taking publishing rights off the editor roles for the window, or by agreement with one named exception. Either way it needs a written record: a dated list of everything that changed after the snapshot. That list is what the delta sync works from, and it is what a revert would have to reconcile.

None of this is visible from outside. The old site stays whole until the switch, so its pages, its forms and its tracking keep working. Mail and any other subdomain stay untouched when the only record that changes is the one the website answers on.

Where the cut happens decides how fast it takes effect.

Behind a CDN that already serves the domain, the cut is an origin change plus a cache purge. Cloudflare documents a purge as deleting “cached content in every Cloudflare data center and cache tier”, and its guidance is to “update or remove the content at your origin before you purge it”, because a request arriving in the other order can cache the old version again. The name visitors resolve never changes, so no resolver cache sits in the way.

At the DNS layer, the cut is a record change, and resolvers keep the old answer for as long as the TTL they already cached. Amazon describes the TTL as “how long you want DNS resolvers to cache the record and use the cached information”, names 172800 seconds, two days, as the typical setting on a name server record, and recommends a value between 60 and 900 seconds while a migration is in flight. The TTL that governs cutover day is the one you published days earlier, so it gets lowered well before the cut and raised again after the rollback window closes.

What has to be true before the old system is retired?

The new site passes a list of checks that one person signs off, and the old system stays up through the rollback window after that. Retiring it is a separate decision taken when the window closes. A fixed list is what makes this something one person can sign on the day.

  1. Every URL in the redirect map resolves to its mapped destination, tested as a full list against the new site. Spot checks pass while the long tail is broken, and the redirect strategy that preserves your traffic covers how that map gets built and tested.
  2. Every page type renders real content, including the types with one single instance.
  3. Forms, search, analytics and every integration fire on the new site, each proven with a test submission that arrives where it should.
  4. The new sitemap is reachable at its stated address and lists the new URLs.
  5. The temporary address is either gone or still blocked from indexing, and the production build does not carry the noindex that the staging build needed.
  6. The old system is up, paid for and untouched, with its database backed up as of the freeze.
  7. One named person can call the revert for the length of the window, without convening a meeting.

A stack that has already been torn down cannot be rolled back to, so the old system stays paid for and running until the rollback window ends. On our own headless migration projects that window is two to three weeks after the cut. Editors publish in the new CMS throughout it, and on switch-over day the decision to switch back is ours rather than the client’s. Watching runs longer than the window: every URL is mapped before cutover and the redirect map stays ours to watch in Search Console for the 30 days after the cut.

What is the way back if cutover day goes wrong?

The way back is pointing the domain at the old system again. It works while five things hold: the old system is still serving, the record you changed can be reverted inside the TTL that resolvers cached before the change, the cache in front of it can be purged, the old URLs still answer on the old server, and whatever has been published in the new CMS since the cut can be put back into the old one.

Precondition Why it decides the way back How you make it true
The old system is still serving You can only point a domain at something that is still up Keep the old hosting and the old CMS paid and running past the cut
The TTL was lowered in advance A reverted record is only as fast as the value resolvers cached before you changed it Lower the TTL on the record you will change days earlier, then raise it when the window closes
The cache in front can be purged An edge that still holds the new pages keeps serving them after a revert Know the purge call for your CDN, test it before the day, and change the origin back first
The old URLs still answer A revert puts the old server back in charge of its own URLs, so the new map comes off Keep the forward redirect map as configuration you can disable in one deploy
Post-cut changes can be recovered Anything created, edited or deleted in the new CMS after the cut is unknown to the old one Keep a dated list of what changed since the cut, and agree who puts it back if nothing syncs in that direction

Publishing in the new CMS during the window needs a recovery plan to go with it. Everything created, edited or deleted there after the cut is unknown to the old system, and whether any of it can come back depends on the two systems you have: check whether anything syncs in that direction before you need it. Where nothing does, putting the changes in by hand is the option left. Either way the plan needs a dated list of what has changed since the cut, so a switch back is a question of how long recovery takes rather than of what went out.

Cutover day as a loop. The old site answers every URL while publishing is paused. Then the final content sync, the checks signed off, the cut that points the domain to the new site, and the rollback window with traffic and checks watched. If the window closes cleanly, the way back is retired. If a check fails or traffic slows or stops, the domain is pointed back at the old system, which still answers every URL
Cutover day, with the way back.

Amazon’s runbook for moving a domain’s DNS service builds the way back into the procedure, and the pattern carries over to a site cutover. It tells you to write down the values you are replacing, because “If you need to revert to the current DNS configuration, these are the servers that you’ll specify”, and then to watch traffic, with the instruction that if it “slows or stops” you change the records back and work out what went wrong afterwards. It is blunt about what the TTL decides: lowering it “reduces downtime for your domain if you discover a problem”, and if you skip that step “your domain could be unavailable on the internet for up to two days if something goes wrong”.

The way back is cheapest while search engines still have the old URLs. Once the new ones are being crawled and indexed, a revert becomes a second site move, with its own redirect map pointing the other way and its own reprocessing window. Google’s timing guidance is that a small to medium-sized website “can take a few weeks for most pages to move”, and the crossover arrives long before that finishes. After it, fixing forward is the cheaper call even when the fault is real: a missing redirect gets added, a broken template gets deployed again, and the index keeps moving one way.

How much moves at once is the other lever on the size of the risk, and Google’s guidance splits by site size.

How much moves at once What Google documents What it does to the way back
Every URL in one cut Recommended for a small or medium site, “moving all URLs on your site simultaneously instead of moving one section at a time” One redirect map, one window, one decision
One section at a time “You can choose to move larger sites one section at a time” A smaller map per cut and a way back that touches less of the site, and two systems in production for longer

Give the window a stated end, because an open one keeps two systems in production and the decision sits with nobody. Two things have to line up for it to close: the stated duration has run, and the check list has passed with the first full crawl of the new site coming back clean. If the crawl is clean early, the window still runs its length. What to watch from that point on is what to watch in the first 30 days, which picks up where cutover day stops.

What is different about migrating off WordPress?

WordPress has a built-in export, and it carries a lot: posts, pages, custom post types, comments, custom fields, categories, tags, custom taxonomies, users and navigation menus, in one XML file in the WordPress eXtended RSS format. What the file does not tell you is what the content means. Every post type sits in the same database table, told apart only by a post_type column, and much of what makes a page look the way it does is stored as markup or plugin data around the text.

What you have How it comes off WordPress
Posts, pages and custom post types All in one table, wp_posts, told apart by post_type. The export includes them, except post types registered with exporting switched off, and it skips auto-drafts
Custom fields Post meta in wp_postmeta, exported with the posts. The REST API shows a field only if it was registered with show_in_rest, which defaults to false, so a field missing from the API can still exist in the database
Block editor content HTML in post_content, with each block marked by an HTML comment that holds its attributes as JSON. Reusable blocks are a separate hidden post type, referenced by ID
The media library Attachments are posts of their own, linked to a parent post, with files in wp-content/uploads and extra image sizes generated for each upload. The export carries each file’s URL, not the file, so the files have to be fetched from those URLs
Taxonomies Categories are hierarchical, tags are flat, and custom taxonomies sit beside them across three term tables. A custom taxonomy is in the REST API only if it was registered with show_in_rest
Users and authors Exported with the content. Through the REST API, a caller without the right to list users sees only users who have published posts
The REST API Routes under /wp-json/wp/v2/, at most 100 records per request, totals in the X-WP-Total header. The content as stored, before WordPress filters it for display, comes back only in the edit context, which needs edit rights
Moving a site off WordPress, posts and pages, custom fields, the media library, taxonomies and authors come across as content. The layouts a page builder stored for each page, plugin behaviour, templates, forms, and anything that ran on the server on each visit get rebuilt.

Page builders and shortcodes do not survive a flat export. Elementor stores a page’s data and layout as JSON in post metadata, a private custom field the WordPress dashboard does not show, so the layout has to be rebuilt as components. Shortcodes are the same problem at a smaller size: they are stored as bracket text and turn into output only when the plugin that registered them runs at display time, and without that plugin WordPress treats them as plain text. Dynamic blocks behave the same way outside WordPress, where server-generated content may not appear. Count which builder and which shortcodes each page uses before you scope the move, because that count decides which pages are migrated and which are rebuilt.

URLs depend on the permalink setting. Plain permalinks put the post ID in a query string such as ?p=123, and the other settings build the path from the date, the post name or a custom structure of tags such as %postname%. Category and tag archives keep a base such as /category/ that the settings cannot remove. WordPress also keeps old slugs: when a published post’s slug changes, the old one is stored and a request for it is redirected to the current address, but only when that request would otherwise end in a 404, and not for hierarchical types such as pages. Those old slugs are live URLs, so they go into the redirect map next to the current permalinks. Media URLs are written into the post content itself, so they need rewriting as part of the content move.

What WordPress does well is getting a site running fast and extending it with plugins, of which its directory lists over 77,000 free ones. That is also why the exit is a scoping job, because every plugin that renders content at display time is something the new site has to replace. The full path is on the WordPress to headless migration page.

What is different about migrating off Drupal?

Drupal already stores content as typed entities with fields, so the content model comes across more cleanly than from most traditional systems. The work sits in how that model is spread across the database, in layouts stored per page, and in a URL layer that runs separately from the content. The version you run changes the job. Drupal 7 security support ended on 5 January 2025, and a Drupal 7 site stores translations differently from Drupal 8 and later. What follows is about Drupal 10 and 11 unless it says otherwise.

What you have How it comes off Drupal
Content types and nodes Each content type is a bundle of the node entity type. A single node is spread over four core tables: node, node_field_data, node_revision and node_field_revision
Fields Each configurable field gets its own table, such as node__field_summary, plus a revision table. One field storage can carry the same field on several content types, so map it once
Taxonomy Terms are entities and vocabularies are their bundles. A vocabulary can be flat or a hierarchy, and the hierarchy needs a place in the new model
Media and files Media items wrap file entities, which sit in the file_managed table under public:// or private:// paths. Content from before the Media module may still use plain file or image fields
Revisions and translations Content entities support revisions. From Drupal 8 on, one node holds all its translations under one ID. Drupal 7’s Content Translation module created one node per language instead
The API route JSON:API ships in core, needs no configuration, is read-only by default and returns at most 50 items per page. Includes pull referenced entities into the same response

Layouts are the part a field export misses. Layout Builder keeps a page’s custom layout in a field on that node, and that layout is data the new frontend has to rebuild as components. Since Drupal 8.7 the field is not translatable, so one layout override applies to every translation of the page.

URLs come in two layers. Every node has an internal path such as /node/7, and the core Path module puts an alias on top, often generated from patterns by the contributed Pathauto module. Since Drupal 8.8 aliases are their own revisionable entities, so the alias list can be read out as data and becomes the spine of the redirect map. Where the site uses the contributed Redirect module, the redirects it already holds belong in the map too. Check on the live site which addresses answer, the alias, the internal path or both, before you decide what the map covers.

Drupal’s strength is detailed, structured content with authoring and security handled in core. Getting out is mostly a mapping job, because the model already exists and the work is moving it, the layouts and the aliases without losing any of them. The full path is on the Drupal to headless migration page.

What is different about migrating off Wix?

Wix has no site export. Wix’s own documentation states that a Wix site needs to be hosted and operated on Wix’s servers, because the platform is a SaaS product built with Wix’s technology. One slice of your content comes off cleanly through a CSV export. Everything else gets read back off the live site.

What you have How it comes off Wix
CMS collections A CSV export, one collection at a time, including hidden and system fields. Time fields arrive as UTC+0
Blog posts A CSV export of the read-only collection behind the blog, carrying the post text without its formatting. Wix still lists export to another platform as an open feature request
Design and layout Nothing to export. The rendered page is the only specification of your design that exists
Media Pulled off the Wix CDN during the crawl, at the crop each image is served at today

The blog is the part teams underestimate. Posts can still be recovered through Wix’s Blog API, which returns the post body when you ask for it explicitly. That is developer work, and it needs its own phase in the plan.

URLs are more predictable. Wix puts blog posts under a /post/ prefix by default, one level below the blog page itself, so the redirect map for the blog falls out of the post list. Dynamic pages driven by a CMS collection follow a URL pattern, so enumerate them from the collection data first.

Wix is good at the thing it was built for, which is running a site without a developer. The exit is expensive for exactly that reason. The full path, including Velo code and dynamic pages, is on the Wix to headless migration page.

What is different about migrating off Squarespace?

Squarespace does have an export, and it produces a single .xml file that carries less than your site does. Layout pages, text and image blocks, and one blog page with its posts come across. Squarespace names the rest on a no-export list, and all of it gets rebuilt from the live site.

What the file leaves behind, per Squarespace’s own documentation:

  • Every blog page after the first. Only one exports.
  • Album, cover, index, info, calendar, portfolio and store pages.
  • Style settings and custom CSS, so your design has to be read off the live site and rebuilt in code.
  • Audio blocks, video blocks, product blocks, drafts, and content in page-specific headers, footers and sidebars.
  • Your images as files. The export points at them by URL, and Squarespace states that when you deactivate your Squarespace site, the image links also deactivate. Download the media while the site is still live, because Squarespace will not export from a site that is not active and published.

URLs need their own pass. A collection item sits at the collection slug plus the item slug, so a post lands at /blog/example-post. The blog post URL format is a site-wide setting with date and title variables, and Squarespace states that changing it does not retroactively change existing posts. A blog running for years often carries two or three URL shapes, so build the redirect map from a crawl. Changing a slug does not redirect the old address either, and Squarespace’s documentation is blunt about the result: a 404 appears.

Running the export takes minutes. Establishing how much of the site sits outside it is the actual scoping job. There is no content API to fall back on either. The Squarespace developer platform covers commerce, webhooks and reseller provisioning. The detail is on the Squarespace to headless migration page.

What is different about migrating off Webflow?

Webflow has two exports and they cover different halves of the site. Code export produces a ZIP of the HTML, CSS, JavaScript and Assets panel images, with the CMS left out, so an exported site renders Collection lists as the empty state and Collection pages without their field-bound content. Only the primary locale is in there, and code export is a Workspace plan feature that Site plans do not include. Content leaves separately, one Collection at a time, as CSV.

What you have How it comes off Webflow
Collection items A CSV per Collection, archived items included, carrying the Item ID Webflow uses to match rows
Rich text Exports as HTML, so the markup survives
References Plain text or URLs, like most field content. Multi-reference fields become a comma separated list
Images and files Webflow-hosted URLs, not the files themselves, and Webflow warns they break if you delete the site
Locales One export per locale. The CSV carries only the locale you are viewing

Download the media while the Webflow site is still published. The Data API is the other route into the content, capped at 100 items per request. Staged and published items sit on separate endpoints, and locales are selected by ID.

URLs follow a rule you can enumerate. Each Collection has a Collection URL, the folder slug sitting in front of every item, so a Blog Posts Collection with the Collection URL post puts its items at /post/your-blog-post. Webflow also exports your existing 301 redirects to CSV, which hands you the redirect history the site already has. Those rules are relative to the root domain and do not apply to localized slugs, so a multi-locale site needs a second pass.

Webflow is good at what it was built for, which is letting a designer run a site without a developer. Getting out means running the design and the content as two separate jobs, because Webflow sends them through two separate doors. The full path is on the Webflow to headless migration page.

What is different about migrating off Sitecore?

Sitecore has no single export file, and which routes out you have depends on the product. XM is the content management core, XP is XM plus the xConnect and xDB marketing stack, and XM Cloud documents the Authoring and Management GraphQL API at /sitecore/api/authoring/graphql/v1/.

What you have How it comes off Sitecore
The item tree The ItemService REST API reads an item by ID or path, its children, or a search result, with language and paging parameters. Its default security policy denies remote clients, so it gets switched on first
Templates and renderings Sitecore Content Serialization writes YAML files into paths you name in a module file. Sitecore’s own XM Cloud guidance is to serialize developer-controlled items rather than the content tree
Versions and languages The Master database holds all versions of all content. The Web database holds only what was published to that target
Presentation XML in two fields. The Renderings field is shared across languages and versions, the Final Renderings field is versioned, and the two get merged at render time
The Media Library Each upload is a blob plus a media item holding size, height, width and blob ID. The blobs sit in SQL by default, or in Azure Blob Storage

Language fallback does not survive a flat export. An item can exist in ten languages with content in two, the rest falling back to another language at item or field level, so count what is actually translated before you scope the move.

URLs are assembled from the item path plus a handful of settings, so the map comes out of configuration. useDisplayName decides whether the display name or the item name goes in the URL and is false by default, languageEmbedding takes asNeeded, always or never, and languageLocation puts the language in the path or a query string. Aliases sit outside all of that. An alias lets one content item answer on any number of extra URLs, and Sitecore’s documentation notes that this can confuse search engines. Each one is a live URL that needs a redirect.

Optimizely sits in the same family of large platforms and has its own way out. On Optimizely CMS 12 the Content Delivery API is the route to the content. Optimizely Graph, the GraphQL layer, builds on that API on CMS 12 and syncs automatically on Optimizely’s SaaS CMS.

Adobe Experience Manager keeps everything in a JCR repository built on Apache Oak, with each page stored as a tree of nodes. Structured content kept as Content Fragments comes out through the GraphQL API, and Adobe has deprecated Content Fragment support in its Assets HTTP API in favour of an OpenAPI delivery API. Pages built from components leave as repository content, which Package Manager exports as zip packages.

Sitecore is good at what it was built for, which is running large multi-site, multi-language estates with editorial workflow and role separation. Getting out means treating the item tree, the presentation XML and the URL configuration as three separate jobs. The detail is on the Sitecore to headless migration page.

What is different about migrating off a custom or in-house CMS?

A custom system usually has no standard export, no vendor documentation, and internal documentation that is thin or out of date. Three things that are normally lookups become work in their own right: getting the content out, establishing the content model, and building the URL inventory. The rest of the migration runs as any other.

What a migration normally reads off the platform Where it comes from on a custom system
The content The database, an internal API, or a crawl
The content model Internal documentation where it exists, the templates where it does not
The URL inventory The sitemaps, the server logs and a crawl, combined
The media The database, the file system or external storage

The three routes are not equivalent. Database access gives you the application’s own structure, including rows no template has rendered in years, but not what is stored outside the database, which is where media often sits. An API gives you what the application was built to expose. A crawl gives you the rendered page, with content bound to its markup. Which combination you need is a question for whoever maintains the system.

Where the content model is not written down anywhere reliable, the templates are the best way to reconstruct the page types a visitor sees: count what they branch on rather than what the navigation shows. They are not the whole model, because fields that feed an integration, a workflow or a report are read by something other than a template. Read the templates and the database against each other, and treat the difference as a question.

The URL inventory rewards starting early. Google’s first-named source for a list of old URLs is the platform: “Use your content management system, which can typically provide a straightforward way to get a listing of all URLs that host content.” Where a custom system cannot produce that listing, the other sources Google names carry it: your sitemaps, your server logs for “URLs that were visited at least once recently”, and the pages Search Console reports as linked. Add a crawl of your own, because logs only hold what somebody visited and a sitemap only what somebody submitted.

Four things are worth establishing before you ask for a quote: whether database or API access is available and who grants it, whether the content model is documented anywhere, how many page types the templates define, and how many URLs the logs and sitemaps show. With those four a provider can scope the work, and the headless audit is that pass.

Three starting points for a headless migration and what changes in the job. From a legacy all-in-one CMS such as WordPress, Sitecore or TYPO3, content comes out through a documented export or a known API, the content model is read off the existing schema, and redirect risk is high because the URL structure often changes. From a custom or in-house system there is usually no standard export, content comes out of the database, an API or a scrape, the content model is worked out from the templates, and redirect risk is high with the URL list taken from the live site and the logs. From another headless platform the content is already structured, it comes out through a vendor export or API, the model is mapped field by field, and redirect risk is lower because the URLs often stay the same
Where you start decides how much of the job is discovery.

What is different about moving between two headless platforms?

The content is already structured, so extraction stops being the hard part and model mapping takes its place. Field types, rich text, references, localisation and assets each need an equivalent on the other side. Where you keep your existing routes, the frontend can survive with a changed data layer and the redirect risk stays smaller than a legacy move.

What is moving What to check for your own pair
Entries and fields Which of your field types have an equivalent on the other side
Rich text How the two structures convert, tested on a link, a table and an embed
References How the destination resolves links on import, and whether your IDs survive
Localisation Which translation model each end uses
Assets Whether the export carries binaries or only points at them

Both ends document their own half, and reading them together is the scoping job. Sanity’s export writes an archive holding “Every exported document, one JSON object per line” with the image and file binaries. Storyblok points at its CLI for “commands to export and sync” stories and folders, and says that “Backups in Storyblok do not include story versions, presets, space settings, or actual assets”. Read the destination’s import documentation in the same sitting: it decides the order you work in.

Field types are where the estimate moves. Storyblok stores rich text as JSON, “based on the TipTap Editor”; Sanity stores block content as Portable Text, “an open specification for structured block content”. Two JSON formats are not one JSON format, so rich text goes through a conversion with its own test cases.

Localisation can change the content model rather than only the data. Storyblok documents field-level translation as “a good choice if the structure of your content across different language versions is similar or identical” and folder-level as “preferable when content varies by locale”. Sanity names the publishing consequence: field-level “Requires you to publish content in all languages simultaneously”, while document-level “Lets you publish each language version independently”. Settle which model you are landing in before the import.

Routes often survive, because the routing lives in the frontend rather than in the CMS. Where you keep the frontend and its route definitions, the redirect map shrinks to whatever you chose to restructure. Check rather than assume: generated slugs, locale prefixes and anything the old platform resolved for you are where addresses move unasked. On cost, how a headless migration gets estimated covers what a provider needs before quoting.

What is the biggest risk in a headless migration?

Losing your search traffic. The redirect map is what decides it, more than the design, the CMS choice, or the build. A site that has been live for years has accumulated ranking signals across hundreds or thousands of URLs, and a poorly planned move can erase that in a single deployment. The fix is treating redirects as a first phase deliverable rather than a launch-week checklist item.

A 301 redirect tells search engines a page has permanently moved, and Google confirms that 301 and other permanent redirects do not cause a loss in PageRank. That only helps where the redirect exists: an old URL without one sends its visitors and its incoming links to an error page. Do not send every old URL to the new homepage either. Google warns that redirecting many old URLs to one irrelevant destination, such as the home page, might be treated as a soft 404.

This is the part that most rewards care, so it gets its own deep dive in the redirect strategy that preserves your traffic. The first weeks after launch are where gaps surface, and what to watch in the first 30 days covers the monitoring that catches them while they are still fixable.

How long does a headless migration take?

Plan for 12 to 18 weeks from discovery to go-live for a typical project, then a separate window for search engines to catch up. The project timeline depends on how many page types, languages, and integrations are in scope. The reindexing timeline is out of your hands and runs in parallel after launch.

Reindexing runs on a clock you do not set. The part you do control is how long the redirects stay up, and Google’s guidance is to keep redirects live for at least a year. Plan for them to outlast the point where the new site stops feeling new to your own team.

A traffic dip after a move is normal while Google reprocesses the redirects, and Google describes that processing as taking a variable amount of time rather than a fixed one. Watch the shape rather than the calendar. A dip that is levelling off is the expected picture, and one that is still deepening is the signal to go looking. What to watch in the first 30 days lists the causes worth ruling out in order.

Five things move the project side of the number, and a provider needs all five before a quote means anything.

What gets counted Why it moves the number
Page types Each one is a content model, a template and its own round of checks. To illustrate: twelve page types across 2,000 pages can be more work than three across 10,000, where the content behind them is comparable
Languages Every page type needs a translated model and a URL pattern, and each language has to be complete for the pages in that cut before it happens
Integrations Forms, search, analytics, commerce and the CRM each need a test submission that arrives where it should, which is build work and then verification work
How much content moves The bulk import is machine time. What cannot be mapped automatically is either transformed in code or re-entered by a person, and neither scales with the hardware
How clean the URL inventory is A site with one URL shape is a short mapping job. One carrying years of slug changes, aliases and campaign URLs is a long one

How the project is run moves the number alongside the technical scope, because every approval round adds effort and time of its own. How a headless migration gets estimated covers that side of it.

How much does a headless migration cost?

A full migration has a fixed project fee, scaled to the number of page types, languages, and integrations. Ongoing technical ownership after launch is separate, billed monthly, and it is optional.

Fixed pricing matters more than the number itself. Hourly billing on a migration creates an incentive to draw the work out and turns every scope question into an invoice. A fixed price set after a proper scoping pass means the budget is known before the build starts. The full breakdown of what each tier includes is on the headless migration service page.

A quote you can hold someone to names what is in it. Read any migration plan for these six:

  1. The page type inventory, counted and named, because that is what the fee is scaled to.
  2. The URL inventory and the redirect map as a deliverable with a date, not a launch-week task.
  3. The content model, including which fields are translated and which are shared across languages.
  4. The integration list, each one with how it will be proven to work on the new site.
  5. The cutover plan: the freeze, the check list, who signs it, and how long the way back stays open.
  6. What happens after launch, what it costs monthly, and whether it is optional.

A plan missing the second or the fifth is the one to ask about, because those two are where a migration stops being recoverable. The cost of getting either wrong is measured in organic traffic rather than in the project fee, and traffic that fed your pipeline comes back on its own schedule, if it comes back at all.

How do you migrate without losing your search rankings?

The sequence that protects rankings:

  1. Crawl every URL first.
  2. Identify the ones with traffic or backlinks.
  3. Map each to its new home one to one.
  4. Implement the redirects server-side as 301s.
  5. Test the full list against the new site before launch.
  6. Watch the indexing report and 404s for the first month.

Rankings survive a migration when the redirect map is complete and the monitoring catches what slipped through.

Server-side 301s are the only reliable option. Client-side redirects through JavaScript or meta refresh are unreliable for search engines, and redirect chains, where A points to B points to C, add latency and weaken the signal at every hop. Google follows up to ten hops but recommends pointing A straight to its final destination.

We have seen a redesigned site lose 40 percent of organic traffic within two weeks, and the cause was never the design. It was a redirect map nobody treated as a priority. The proof that it can go the other way is the Eversports migration: WordPress to Storyblok across six languages, with rankings intact.

Is a headless migration the right move for you?

It is the right move if:

  • your team is blocked by the CMS
  • your site is slow
  • you are managing more than one market and the current setup makes that harder than it should be

It is the wrong move if:

  • you have a small static site that rarely changes
  • you have no internal team to own a frontend after launch

The honest answer depends on what you are working with today, and the work is different depending on where you are starting from. We have written up what the move looks like from WordPress, Webflow, Wix, Squarespace, Drupal, TYPO3, Umbraco, Sitecore, Kentico and Contentful.

The way to find out without committing to a full project is a headless audit. We crawl your current site, measure where it actually stands on performance, map the migration scope including the redirect work, and tell you whether a move is worth it. If it is not, we say so. If it is, you start the migration with the scope already understood and the budget already fixed, which is the difference between a project that lands on time and one that does not.

Essential Code is your Fractional Marketing Engineer: a small senior team that joins your marketing team and builds what your marketing plan needs.

How the service worksNot sure yet? Start with an auditOr email us directly