Contentful to WordPress migration: The complete enterprise guide

Your marketing manager just filed her third ticket this week, asking for one more content field in Contentful. Somewhere at the top of your inbox, a billing email with the word “overage” is still unread.

That’s the point you might want to consider a Contentful to WordPress migration. This guide covers the business case around this decision, the architecture involved, the execution, and the steps after going live.

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

If you’re still evaluating whether to move at all, the Contentful vs WordPress comparison will have you covered.

Why enterprises leave Contentful

Trouble around the pricing model

Contentful’s pricing grows across six dimensions simultaneously: API calls, CDN bandwidth, roles, spaces, users, and locales.

The Lite plan starts at $300/month, while the Premium plan is custom-priced. Vendr’s buyer transaction data puts the median contract at over $50,000/year.

Contentful contracts may include annual price escalations of 3–7%, and Vendr’s data suggests that buyers who accept initial quotes without citing budget limits or alternatives tend to pay more than those who push back.

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 around $2,000/month.

After migrating from Contentful to WordPress, Emplifi’s CMS fee savings were reported at over $4,000 per month.

WordPress VIP starts at $25,000/year with no per-seat costs or API overage fees.

Your editorial team is still filing tickets

Restructuring a content type in Contentful either needs admin-level access or a developer writing a migration script.

However, WordPress’s Gutenberg block editor is a WYSIWYG experience. A marketing manager can build a new landing page without filing a ticket.

PhantomBuster’s publishing time fell from 90 minutes per article on Contentful to 10 minutes on WordPress.

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 editorial workflow change happened simultaneously.

Choose your migration path first

Not every Contentful migration has the same result. 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 WordPress is the solution.

This guide covers both, with a decision framework for choosing between either of 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	Monolithic (traditional) WordPress
Run a marketing site with modest dev resources	Monolithic WordPress
Need WordPress as a content backend for multiple frontends	Headless WordPress
Want WordPress VIP with full managed platform support	Monolithic WordPress
Are on a Jamstack or edge-deployed frontend	Headless WordPress
Are migrating from headless Contentful and want to drop the decoupled frontend	Monolithic WordPress

The headless path

This replaces Contentful as the content backend while the frontend stack (Next.js, Nuxt, etc.) stays intact. The primary work is swapping the Contentful SDK for WPGraphQL queries, remapping the content model, and rebuilding Rich Text rendering logic.

rtCamp’s open-source SnapWP framework provides a foundation for headless WordPress with WPGraphQL. SnapWP keeps your existing WordPress designs, styles, and page structure working on a headless frontend.

The traditional path

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

Pre-migration: discovery and planning

Close attention to the discovery and planning phase is important to prevent problems from showing up when it’s too late.

Content inventory and audit

1. First, run the contentful 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.
2. Parse the export to generate a frequency map: entry counts per content type. Don’t write transformation scripts until you’ve reviewed this map.
3. Sort content into three buckets:
   – Migrate: Active, high-traffic, brand-relevant
   – Update: Needs revision before or during migration
   – Retire: Outdated (archive or delete)

Supplement this with Google Search Console 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

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 or ACF text or textarea field, or native post_title/post_content
Rich Text field	post_content (HTML) or Gutenberg block markup
Reference (linked entry)	Pods or ACF Relationship field + post ID lookup table
Array of references	Pods or ACF Relationship field (multi-select) or  Repeater/Group field
Asset (image/file)	WordPress Media Library (attachment post type)
Locale field variants	Separate translated posts via WPML, Polylang, or MultilingualPress
Space	Standalone WordPress install or Multisite network
Environment	WordPress staging environment (host-provided or plugin-based)
Tag	WordPress tag taxonomy
Webhook	WP-Cron or Action Scheduler for scheduled tasks; outgoing webhooks via plugin (e.g., WP Webhooks) or custom REST API endpoints

If a property needs filtering or navigation, use a taxonomy. If it’s descriptive metadata only, use post meta. Author and contributor references can 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 options. Meta Box, Carbon Fields, and Toolset are all well-maintained alternatives.

The trickiest part of any Contentful-to-WordPress migration is reference mapping. Contentful links entries to each other using internal IDs (sys.id), and WordPress uses its own post IDs. A mapping table that connects the two must be built at the start of the migration and kept intact throughout the process. If that table is lost or corrupted, every cross-reference in the migrated content will break.

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. Follow these steps to preserve SEO after migration:

1. Build a complete URL inventory before you touch anything else, with all indexable pages, top organic landing pages from Search Console, highest-backlink URLs from Ahrefs or Moz, sitemap entries, and vanity and campaign URLs.
2. Map every old URL to its new WordPress permalink and implement it via the Redirection plugin or server-level 301s.
3. Avoid the temptation to redirect everything to the homepage, because Google treats that as a soft 404 and you’ll lose SEO equity by doing so.
4. 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.

Drops in traffic after a migration are often the result of incorrect redirection, an action that is entirely within your control.

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

The migration process

Exporting from Contentful

Automattic Special Projects and Emplifi both used a method that skipped using a WordPress plugin for the data load:

Contentful CLI export → JSON → custom transformation scripts

The export is a single JSON file. For large spaces, paginate using the Content API’s cursor-based pagination. Before writing any transformation code, compare entry counts per content type against the Contentful dashboard. This check takes about an hour and can save days of rework.

The Rich Text problem

Contentful’s Rich Text format is a proprietary JSON document tree. It can’t be imported into WordPress directly, and every Contentful migration requires a transformation step here, which is 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. This is reliable, straightforward to implement, and 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 since it requires custom development. The advantage 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. It is worth the custom development investment for any organization planning long-term on WordPress.

Embedded entries and assets are the hardest part. Contentful Rich Text stores them as reference pointers (sys.id). Before conversion begins, make sure you map every Contentful entry and asset ID to its WordPress equivalent.

Always import assets before entries. Entries reference assets by ID, so the WordPress attachment IDs need to exist before any entry tries to point to them.

Asset migration

Every Contentful asset is served from images.ctfassets.net, the CDN URLs authenticated against your Contentful organization account. When the subscription ends, every image will return a 403.

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

Custom PHP scripts should be executed via wp eval-file, since browser-based processes are prone to failure.

Here are some critical implementation details from Automattic Special Projects:

• Set define('WP_IMPORTING', true) at script start. This suppresses publish notifications, pingbacks, and subscription emails during import.
• Use the Rule of 1-2-10 to import 1 entry and verify manually, then 2, then 10. After the 10-entry run, benchmark execution time to estimate the full import duration. Only then run against the complete dataset.
• Store the raw Contentful import data in WordPress post meta. This makes debugging easier and helps ensure reruns don’t create duplicates.
• Import as draft status first, spot-check across content types, then bulk-publish. Make sure WP_IMPORTING is still defined when changing post status to avoid triggering notification hooks.

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 will focus 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 Contentful query in the frontend codebase needs a rewrite.

Pagination

Contentful uses offset-based skip/limit with a totalfield. 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 Contentful query requires a rewrite, and this is the most significant frontend code change in the migration.

Nested query complexity

Contentful enforces a default 11,000-entity complexity budget per request and an 8KB query size limit. Premium plans can bypass the size limit with persisted queries. WPGraphQL has no built-in complexity or size caps and uses DataLoaders for batched resolution. Queries still need restructuring, but WPGraphQL’s constraints are less restrictive at the API layer.

Asset handling

Contentful lets you resize and reformat images directly in a GraphQL query using url(transform: { width: 200, format: WEBP }). WPGraphQL takes a different approach: WordPress generates image sizes at upload time (thumbnail, medium, large, etc.), and WPGraphQL lets you pick which one you want via sourceUrl(size: LARGE).

Rich Text handling also gets simpler. Contentful delivers content as structured JSON that requires a dedicated rendering library (@contentful/rich-text-react-renderer) to convert into displayable HTML. WordPress stores content as ready-to-render HTML, so that entire library layer disappears from the frontend codebase.

Before switching over, run Contentful and WordPress backends in parallel on staging and compare GraphQL responses field-by-field.

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

The traditional WordPress theme migration

For teams moving to a WordPress theme and wanting editors to own the full publishing experience, the benefit for editors 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.

Multilingual migrations require a separate plan

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

Contentful stores localizations at the field level with one entry for 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 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 provide programmatic APIs for bulk import. WPML uses the wpml_set_element_language_details action hook, Polylang uses pll_set_post_language() and pll_save_post_translations(), and MultilingualPress exposes a ContentRelations API.

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 in when you select a plugin for this aspect.

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 or 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 will catch content rendering issues, truncated text, wrongly formatted pull quotes, broken relationship fields, and missing image captions.

Run Core Web Vitals (PageSpeed Insights), GTmetrix, and Time to First Byte (TTFB) benchmarks in staging against the live Contentful baseline before launch to track the benefits of the migration.

Pre-launch checklist

Go-live

These are the steps you’ll need to follow:

1. 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.
2. Keep the Contentful subscription active for a cooling period of at least two weeks after launch.
3. 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

After migrating to WordPress from AEM, Manheim’s marketing team went from full developer dependency to building and publishing pages independently. At The Indian Express, editors publish breaking news faster since moving to Full Site Editing in WordPress.

Focus early training on block editor basics, content model conventions, media management, SEO meta fields, and editorial workflow and roles.

A one-page reference card for the five most common editorial tasks will help reduce support queries.

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 61,000+ free plugins cover most integrations without the need for custom development. For organizations that built custom Contentful integrations, the same principle applies on WordPress, with more community-maintained starting points.

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.

Below are 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 to track organic traffic trends, Core Web Vitals, lead form conversion rates, and editorial publishing speed.

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.

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.

Get in touch

Book a free migration consultation if you’d like to know more about our migration services.

If you’re still evaluating, our Contentful vs WordPress comparison guide has the details.