Contentful to WordPress migration: the complete enterprise guide

You might recall the time your marketing manager filed her third ticket this week asking for a content field for your platform built using Contentful. Some day soon, a bill with the word “overage” arrived.

This is when you might wish to consider a Contentful to WordPress migration for your platform. This guide covers that process with a focus on the business case, the architecture decision, the technical execution, and the next steps.

Traditional WordPress and headless WordPress (WordPress + WPGraphQL) are the targets, with a decision-making framework provided to help you choose between them.

The technical steps are written for engineers, and the cost and operational details are meant for people who sign the contracts.

If you’re still evaluating whether to move at all, the Contentful vs WordPress comparison covers that question in full. This guide assumes you’ve made the call.

Why enterprises leave Contentful

The pricing model scales against you

Contentful’s pricing grows across six dimensions simultaneously: API calls, CDN bandwidth, roles, spaces, users, and locales, each independently, by design. When all six are moving, your bill rarely moves in one direction.

The Lite plan starts at $300/month. The Premium plan is custom-priced. Vendr’s buyer transaction data puts the median contract at $33,000/year, with an average over $81,000/year, and enterprise deployments routinely reaching six figures once locales, spaces, and user counts scale.

Most renewal contracts carry a 3–7% annual escalation clause. Vendr notes that buyers who don’t negotiate often accept the initial renewal quote without pushing back. Your traffic doesn’t need to grow for the bill to.

The deeper issue is that your pricing risk isn’t tied to business outcomes, it’s tied to editorial ambition. A Trustpilot reviewer documented Contentful reducing their plan from 4 locales to 3 without the customer initiating the change, forcing a tier upgrade from $300/month to roughly $2,000/month. Nothing about their usage changed, Contentful changed the terms around them.

Emplifi documented $4,000+ per month in CMS fee savings – $48,000/year after migrating from Contentful to WordPress.

WordPress VIP starts at $25,000/year with no per-seat costs and no API overage fees. The cost floor is higher, but the cost ceiling doesn’t exist.

Your editorial team is still filing tickets

Adding a field, changing a validation, restructuring a content type, none of this can be done by a content editor in Contentful without either admin-level access or a developer writing a Content Management API (CMA) migration script.

For marketing teams running at editorial pace, that creates a permanent bottleneck. The question isn’t whether your developers are responsive. It’s whether they should be the ones gatekeeping content structure in the first place.

PhantomBuster’s team spent 90 minutes per article on Contentful. After migrating to WordPress, that dropped to 10 minutes, a 90% reduction in publishing time, with a 20% increase in organic traffic achieved without any content modifications.

The pattern holds at smaller scale too. One Capterra reviewer noted “a bit of a steep learning curve when coming from a traditional CMS platform such as WordPress,” while a JoinSecret reviewer found that content changes can take “up to 15 minutes to show up on preview pages.”

WordPress’s Gutenberg block editor is WYSIWYG from day one. A marketing manager can build a new landing page without filing a ticket. That shows up in publishing velocity in ways that compound over time.

Foursquare’s migration from Contentful to WordPress, completed in 12 weeks, produced a 54% improvement in page load times, from 7.0 seconds to 3.1 seconds. The engineering work and the editorial workflow change happened simultaneously.

Leaving is harder than the pitch implied

Three structural mechanisms increase migration complexity beyond what most teams anticipate.

The Rich Text format

Contentful stores rich content as a proprietary JSON abstract syntax tree. It can’t be pasted into any other CMS or parsed by generic tools. Every migration requires a custom converter, and no off-the-shelf library handles the Contentful Rich Text to WordPress transformation end-to-end.

No native URL structure

Every URL lives in the frontend code, not the CMS. That means the redirect map has to come from the frontend routing logic, not the export file, an extra discovery step most teams don’t anticipate until they’re already deep in the content audit.

API rate limits on your own export

The Content Management API (CMA) runs at 7 requests/second by default on non-enterprise plans, with higher limits available at the enterprise tier. Large spaces require batched exports before migration work can even begin.

None of this prevents migration, but all of it prevents a fast one.

Choose your migration path first

Not every Contentful migration lands in the same place. If you’re running a React or Next.js frontend you want to keep, headless WordPress with WPGraphQL is the right target. If you want editors to own the full publishing experience without a decoupled frontend, traditional coupled WordPress is. This guide covers both, with a decision framework for choosing between them.

If you…	Go with…
Have a React/Next.js frontend you want to keep	Headless WordPress + WPGraphQL
Want editors to own the full WYSIWYG experience	Coupled (traditional) WordPress
Run a marketing site with modest dev resources	Coupled WordPress
Need WordPress as a content backend for multiple frontends	Headless WordPress
Want WordPress VIP with full managed platform support	Coupled WordPress
Are on a Jamstack or edge-deployed frontend	Headless WordPress
Are migrating from headless Contentful and want to drop the decoupled frontend	Coupled WordPress

The headless path

This replaces Contentful as the content backend while the frontend stack (Next.js, Nuxt, etc.) stays largely intact. The primary work is swapping the Contentful SDK for WPGraphQL queries, remapping the content model, and rebuilding Rich Text rendering logic. WordPress stores rendered HTML rather than a JSON AST, which removes the entire @contentful/rich-text-react-renderer layer from the frontend codebase. rtCamp’s open-source SnapWP framework provides a foundation for headless WordPress with WPGraphQL.

The coupled path

This puts both CMS and frontend on WordPress. Editors get the Gutenberg block editor from day one. The migration involves building a WordPress theme alongside migrating content.

Both paths start in the same place, a content audit and a data model map.

Pre-migration: discovery and planning

The migration itself is rarely where projects fail. Discovery is where they either get set up correctly or inherit problems that compound for months.

Content inventory and audit

Run contentful space export via the Contentful CLI. The output is a single JSON file containing all content types, entries, assets, locales, webhooks, roles, and editor interfaces. Key flags: --include-drafts, --download-assets, --environment-id.

Parse the export to generate a frequency map: entry counts per content type. Don’t write transformation scripts until you’ve reviewed this map. The number of entries rarely matches what teams assume.

Sort content into three buckets:

• Migrate: active, high-traffic, brand-relevant
• Update: needs revision before or during migration
• Retire: outdated (archive or delete)

Supplement with Google Search Console (top organic URLs) and Screaming Frog or Ahrefs for backlink data. High-traffic, high-backlink URLs require special handling in redirect mapping and shouldn’t get lost in bulk migration logic.

The CMA rate limit of 7 requests/second (default) means large spaces take time to export. The CLI handles rate limiting automatically. Build this into the schedule and don’t interrupt it.

Data model mapping

Get the data model mapping wrong and transformation scripts run from scratch. Every Contentful content type must map to a WordPress equivalent before any import code gets written.

Contentful concept	WordPress equivalent
Content type	Custom Post Type (CPT)
Short/Long Text field	Pods text or textarea, or native post_title/post_content
Rich Text field	post_content (HTML) or Gutenberg block markup
Reference (linked entry)	Pods Relationship field + post ID lookup table
Array of references	Pods Relationship field (multi-select) or Group
Asset (image/file)	WordPress Media Library (attachment post type)
Locale field variants	Separate translated posts via WPML,Polylang, orMultilingualPress
Space	Standalone WordPress install or Multisite network
Environment	WordPress staging environment
Tag	WordPress tag taxonomy
Webhook	WordPress webhook / Action Scheduler

Two decision rules resolve most edge cases. If a property needs filtering or navigation, use a taxonomy; if it’s descriptive metadata only, use post meta. Author and contributor references map to the WordPress Users table or the Co-Authors Plus plugin.

The table above uses Pods as the custom fields layer, but it’s one of several solid options. Meta Box, Carbon Fields, and Toolset are all well-maintained alternatives. The mapping logic in the table above applies regardless of which you choose.

The hardest mapping decisions involve nested reference structures. Contentful’s linked entry model maps cleanly to Pods Relationship fields, but the lookup table connecting Contentful sys.id values to WordPress post IDs must be built and maintained as a first-class data structure throughout the migration. Lose the lookup table and reference resolution breaks.

SEO preservation plan

Contentful has no native URL structure. Every URL lives in the frontend routing code, which means the redirect map has to come from that routing logic, not the export file. Most teams don’t catch this until they’re already deep in the content audit.

Build a complete URL inventory before you touch anything else, all indexable pages, top organic landing pages from Search Console, highest-backlink URLs from Ahrefs or Moz, sitemap entries, and vanity and campaign URLs.

Map every old URL to its new WordPress permalink and implement via the Redirection plugin or server-level 301s. Avoid the temptation to redirect everything to the homepage — Google treats that as a soft 404 and you’ll lose the equity those URLs carry.

Migrate all meta titles, descriptions, Open Graph (OG) tags, and schema markup to Yoast SEO or Rank Math. Submit a new XML sitemap on launch day.

PhantomBuster saw a 20% increase in organic traffic post-migration when redirects were handled correctly. Traffic drops after a migration aren’t inevitable, they’re usually the result of inadequate redirect planning, which is entirely within your control.

For a complete checklist, see rtCamp’s CMS SEO migration guide.

Stakeholder alignment and timeline

Before any work starts, you need four groups aligned: Engineering on the architecture decision and tooling, Marketing and Content on what gets retired versus migrated, SEO on redirect sign-off and metadata migration, and Legal or Compliance on any data residency or accessibility requirements. Missing any one of these at the start tends to surface as a blocker mid-project.

The gap between technical work and getting a migration fully live is almost always content audits, stakeholder alignment, and governance cleanup, not code. Build in a 20–25% buffer on whatever timeline your team estimates. The teams that skip this are the ones announcing revised timelines to executives later.

The migration process

Exporting from Contentful

Three independent, real-world Contentful migrations converged on the same architecture: Contentful CLI export → JSON → custom transformation scripts. Automattic Special Projects and Emplifi both used this pattern. None used a WordPress plugin for the actual data load.

Export produces a single JSON file. For large spaces with millions of entries, use cursor-based pagination via the Content Delivery API. Validate the export by comparing per-content-type entry counts against the Contentful web UI before writing any transformation code. This step takes an hour and saves days.

The Rich Text problem

Contentful’s Rich Text format is a proprietary JSON document tree. Not HTML. Not Markdown. It can’t be imported into WordPress directly, and every Contentful migration requires a transformation step her, it’s consistently the highest-complexity technical work in the project.

Path A: Convert to HTML

Use the official @contentful/rich-text-html-renderer package (documentToHtmlString()) with custom renderNode handlers for each node type. Store output in WordPress post_content. Reliable, straightforward to implement, handles standard text formatting correctly.

Path B: Generate Gutenberg blocks (recommended for enterprise migrations)

Override each renderNode in @contentful/rich-text-html-renderer to emit Gutenberg block comment syntax instead of HTML:

• <!-- wp:paragraph -->
• <!-- wp:heading {"level":2} -->
• <!-- wp:image {"id":123} -->

No off-the-shelf library does this, it requires custom development. The payoff is that editors get full Gutenberg editing capability after migration rather than a monolithic HTML blob in post_content. The block serialization format is formally specified in the WordPress Block Editor Handbook and defined by a published Parsing Expression Grammar in @wordpress/block-serialization-spec-parser, a stable spec that won’t shift under you. Worth the custom development investment for any organization planning long-term on WordPress, since the editing experience difference shows up from the first day of publishing.

Embedded entries and assets are the hardest part of either approach. In Contentful Rich Text, they appear as reference pointers only (sys.id). During conversion, maintain a lookup table mapping every Contentful entry ID and asset ID to its WordPress post ID or attachment ID, and resolve all references as the document tree is walked. The lookup table must be populated before Rich Text conversion runs.

Import assets before entries, without exception.

Asset migration

Every Contentful asset is served from images.ctfassets.net, CDN URLs authenticated against your Contentful organization account. When the subscription ends, every image returns a 403. Solve this before anything else.t

Use media_sideload_image() to download each asset from Contentful’s CDN and register it in the WordPress Media Library during import. Build an asset ID lookup table (Contentful sys.id → WordPress attachment ID) for reference resolution after import.

Metadata mapping:

• Contentful title → WordPress attachment title
• Contentful description → WordPress alt text

For post-import cleanup, the a8cteam51/wordpress-importer-fixers WP-CLI toolset from Automattic Special Projects handles broken featured image associations and gallery ID mismatches, two of the most common post-migration data integrity issues.

Import architecture and best practices

The pattern across multiple real-world Contentful migrations is clear: custom PHP scripts executed via wp eval-file, not a WordPress plugin. The Automattic Special Projects post documents exactly why, plugin-based ETL approaches hit PHP timeout limits and memory ceilings at scale. Shifting to WP-CLI is what makes the migration work.

Plugins run through WordPress’s admin layer, while WP-CLI scripts run server-side, and for datasets of any real size, that difference matters.

Critical implementation details from Automattic Special Projects:

• Set define('WP_IMPORTING', true) at script start. This suppresses notification hooks and dramatically speeds up writing large amounts of content.
• Import order: assets first → referenced entries → referencing entries. Never import in reverse dependency order.
• Use the Rule of 1-2-10: import 1 entry and verify manually → import 2 → verify → import 10 → benchmark → scale to the full dataset. Running untested scripts against a full dataset is the most expensive mistake in CMS migration.
• Store original Contentful entry IDs in WordPress post meta. This lets you rerun scripts safely without creating duplicates.
• Import as draft status first, review spot-checks across content types, then bulk-publish.

For WordPress VIP deployments: use vip_inmemory_cleanup() after every batch, wrap import with start_bulk_operation()/end_bulk_operation(), and add periodic sleep() calls to avoid database overload in production.

Run the migration at least twice in staging before production. The second run confirms the scripts are rerunnable and the lookup tables are clean. If it produces duplicates, fix the logic before anything touches production.

Going headless: replacing the Contentful SDK with WPGraphQL

If your team is keeping an existing React, Next.js, or Nuxt frontend and swapping Contentful for WordPress as the content backend, the work centres on four schema differences between the two platforms. Install WPGraphQL (free, open-source) and Pods, which has WPGraphQL integration built into core since version 2.9.

Query structure and field naming

Contentful auto-generates its GraphQL schema from content models at request time, using a {contentType}Collection { items { ... } } pattern. WPGraphQL follows the Relay specification: {contentTypePlural} { nodes { ... } } or edges { node { ... } }. Every query in the frontend codebase needs a rewrite.

Pagination

Contentful uses offset-based skip/limit with a total field. WPGraphQL uses cursor-based pagination with first/after (forward) and last/before (backward) arguments, returning opaque cursor strings in pageInfo. WPGraphQL’s creator Jason Bahl documented the design rationale for this approach in 2020. An optional offset pagination extension exists but isn’t recommended. Every paginated query requires a rewrite, this is the most impactful frontend code change in the migration.

Nested query complexity

Contentful enforces an 11,000-entity complexity budget per request and an 8KB query size limit (16KB with Premium persisted queries). WPGraphQL has no equivalent limit and uses DataLoaders for batched resolution. Queries need restructuring, but the WPGraphQL constraints are less restrictive overall.

Asset handling

Contentful provides inline image transforms via GraphQL arguments (url(transform: { width: 200, format: WEBP })). WPGraphQL exposes media as MediaItem connections with pre-generated WordPress image sizes accessed via sourceUrl(size: LARGE). No inline transform — CDN-based transforms require additional tooling.

Rich Text handling also gets simpler on this path. Contentful returns a JSON AST that requires @contentful/rich-text-react-renderer on the frontend. WordPress stores rendered HTML, so the frontend renders it directly, the entire Rich Text renderer layer drops out of the codebase.

Before switching over, run Contentful and WordPress backends in parallel on staging and compare GraphQL responses field-by-field. Don’t compress this step.

rtCamp’s wp-decoupled Next.js + WPGraphQL starter and the SnapWP framework provide a foundation for this path.

Going coupled: the WordPress theme migration

For teams moving to a WordPress theme and wanting editors to own the full publishing experience, the work is more front-end heavy, but the editorial payoff is immediate.

Register Custom Post Types matching the mapped content model and build Pods field groups for each. Develop the WordPress theme with block templates or Full Site Editing (FSE) templates corresponding to each content type’s editorial layout.

For complex landing page structures previously built in Contentful’s content model, map to Pods Flexible Content or native Gutenberg block patterns. Full Site Editing allows headers, footers, archive templates, and single post templates to be managed visually after launch, with no developer involvement required.

Gutenberg is WYSIWYG, supports live preview, and requires no separate preview infrastructure. PhantomBuster’s 90-minute to 10-minute publishing improvement was achieved on this path.

Multilingual migrations require a separate plan

Contentful and WordPress store translations differently, and that gap is where multilingual migrations get complicated.

Contentful stores localizations at the field level: one entry, multiple locale values per field. The structure looks like "title": { "en-US": "My Post", "de-DE": "Mein Beitrag" }. A single entry ID represents all locale versions.

WordPress multilingual plugins (WPML, Polylang, MultilingualPress) all use a post-level model, each translation is a separate post linked to the original. One Contentful entry with 5 locale variants becomes 5 WordPress posts, each requiring creation, language assignment, linking, and ongoing sync.

The migration script must maintain a {contentful_entry_id, locale} → wordpress_post_id mapping table. Non-localized fields must be duplicated or configured as copy-once. Cross-entry references must be resolved per locale.

All three plugins expose programmatic APIs for bulk import. WPML uses the wpml_set_element_language_details action hook, Polylang uses pll_set_post_language() andpll_save_post_translations(), and MultilingualPress exposes a ContentRelations API.

No off-the-shelf tool handles Contentful field-level locale to WordPress multilingual migration. Every multilingual project needs bespoke scripting, but the architectural mismatch is solvable. It adds complexity, not blockers.

WordPress Core’s Phase 4 roadmap targets native multilingual support, which would eliminate the post-duplication model entirely. If your project won’t launch until late 2026 or beyond, that’s worth factoring into plugin selection now.

Testing and launch

Staging and rehearsal

Run the full migration in staging at least twice before going live. The second run confirms the scripts are rerunnable, they should produce no duplicates and no data drift. A third run, if time allows, is useful as a speed benchmark.

Give the editorial team access to staging for User Acceptance Testing (UAT). Editors catch content rendering issues developers miss, truncated text, misformatted pull quotes, broken relationship fields, image captions that got dropped. For enterprise migrations, UAT is not optional.

Run Core Web Vitals (PageSpeed Insights), GTmetrix, and Time to First Byte (TTFB) benchmarks in staging against the live Contentful baseline before launch. Problems caught in staging can be fixed before they reach users; problems caught after launch become incidents.

Pre-launch checklist

Go-live

Schedule the switch for your lowest-traffic window, typically 2–4 am. Run a final content sync for anything published in Contentful after the staging snapshot was taken.

Keep the Contentful subscription active for at least two weeks after launch. Asset URLs from images.ctfassets.net may still be cached in search indexes, social previews, and external links. Cancelling immediately creates broken images that can take weeks to surface in monitoring.

Keep an eye on Google Search Console for crawl errors, your analytics for traffic baseline comparison, and server logs for 4xx/5xx spikes in the first 48 hours.

Post-migration: onboarding and what comes next

Editorial team onboarding

The publishing experience change is the payoff, and it’s worth naming explicitly. PhantomBuster cut publishing time from 90 minutes to 10 minutes per article. Foursquare saw a 54% page load improvement.

After migrating from AEM, Manheim’s marketing team went from full developer dependency to building and publishing pages independently. At The Indian Express, speed-to-market for major news events dropped dramatically after moving to Full Site Editing. Editors control layouts completely without touching code. Both are typical of what editorial ownership of WordPress actually produces.

WordPress VIP includes real-time collaborative editing (Google Docs-style) and Suggested Edits (track changes, currently in development). WordPress 6.9 added block-level commenting via Notes, a core feature available to all WordPress users, not just VIP deployments.

Focus early training on block editor basics, content model conventions (which Custom Post Types serve which use cases), media management, SEO meta fields, and editorial workflow and roles. Keep sessions short and task-specific.

A one-page reference card for the five most common editorial tasks will reduce support tickets more reliably than any hour-long walkthrough.

Integration replacement

Contentful integration	WordPress equivalent
Segment / Google Analytics	Parse.ly (native to VIP), Site Kit, Segment plugin
Bynder / Cloudinary DAM (Digital Asset Management)	Native WP plugins, rtCamp GoDAM
Algolia / Elasticsearch	WP Search with Algolia, ElasticPress, SearchWP
HubSpot / Marketo	HubSpot WP plugin, WPForms, Gravity Forms
Personalization	Parse.ly content insights, Optimizely plugin
A/B testing	Parse.ly Headline Testing, VWO

WordPress’s 60,000+ free plugins cover most integrations without custom development. For organizations that built custom Contentful integrations, the same principle applies on WordPress, with more community-maintained starting points.

On the Parse.ly row specifically: rtCamp integrated Parse.ly for Grist, a nonprofit media organization. In their words: “Parse.ly helps us increase reader engagement and improve our conversion funnels. For example, we are able to know how long readers spend on our articles, and what was the last article read that led to a conversion.” — Jason Castro, Product Manager, Grist.

Performance benchmarks to set

Compare Core Web Vitals before and after using the same device, network, and testing tool — the comparison is only meaningful if the methodology stays consistent.

Results from comparable rtCamp migrations:

• Pasqal: Core Web Vitals (CWV) score 66 → 90
• VinSolutions (Kentico → WordPress VIP): 48% CWV improvement
• KHM Travel: TTFB 0.7s → 0.29s
• FleetNet America (Drupal → WordPress VIP): roughly 2× CWV improvement
• NextGear Capital: 20% increase in lead form submissions
• Greater Kashmir (proprietary CMS → WordPress): 320,000+ articles migrated, 17% increase in mobile sessions post-launch

Set review milestones at 30, 60, and 90 days after launch, organic traffic trend, Core Web Vitals, lead form conversion rates, and editorial publishing velocity. At 90 days you can start separating migration gains from baseline noise.

Governance setup

WordPress’s built-in roles – Administrator, Editor, Author, Contributor, Subscriber map directly to most editorial hierarchies and can be extended further with the User Role Editor plugin.

For WordPress VIP deployments, the VIP Workflow plugin adds custom post statuses (Pitch → Assigned → In Progress → Pending Review → Published) with email and webhook notifications. Staging environments are included at no extra cost.

What this migration costs

If you’re building a business case internally, here are the inputs that matter.

Platform costs

• WordPress VIP: Starts at $25,000/year, no per-seat pricing, no API overage fees
• Contentful Premium: Custom-priced; Vendr buyer data shows a median of $33,000/year and an average over $81,000/year, with enterprise deployments frequently reaching six figures annually as locales, spaces, and users grow. Contracts typically include 3–7% annual escalation clauses
• Emplifi recovered its migration investment through $48,000/year in CMS fee savings alone, before productivity gains were counted

Developer costs

• WordPress developer average US salary: $84,477/year (ZipRecruiter)
• React/headless frontend developer: $110,000–$120,000/year (Glassdoor/ZipRecruiter)

The talent cost difference matters beyond the headline number. Organizations running Contentful-specific frontend engineers are paying a premium that recurs every year, and the WordPress developer market is substantially larger, which means shorter hiring timelines and more competitive contractor rates when you need to scale.

Migration engagement options with rtCamp

rtCamp is a WordPress VIP Premier Agency Partner with 300+ completed migrations across enterprise publishing, media, and business-to-business (B2B) organizations. Engagements are structured in three tiers depending on how much of the work you want to own.

Free consultation (20 hours of scoping)

Contentful setup assessment, architecture recommendation, preliminary timeline and cost estimate, and an honest view of whether migration makes sense now. This includes a documented read-out you can take into internal planning.

Paid discovery (2–3 weeks)

A complete migration blueprint covering content model mapping, Extract-Transform-Load (ETL) architecture, redirect inventory, integration plan, and governance structure. Yours to execute in-house, with rtCamp, or with any partner.

Full migration service

End-to-end from discovery through 90 days of post-launch support, including editorial onboarding and performance validation.

An important calculation

At enterprise scale, Contenful handles complex content models, headless delivery, multilingual sites, and high-traffic publishing smoothly. However, staying with Contentful will lead to rising costs in the form of licensing, editorial bottlenecks, and the complexity of eventually switching.

Book a free migration consultation if you’d like to know more about how we can help you overcome this dilemma.

Or if you’re still evaluating, the Contentful vs WordPress comparison covers the platform decision in full.