WordPress to PayloadCMS Migration: The Complete Technical Guide

This guide is written for engineering leads and CTOs who have decided to migrate from WordPress to PayloadCMS — or who are in the final stages of evaluating the decision. It covers the technical reality of the migration: what breaks, what is automated, how long each phase takes, what it costs, and the gotchas that derail projects which do not plan for them.

Estimated reading time: 15 minutes. Estimated migration timeline: 4–8 weeks. Cost range: £8,000–£25,000 depending on content volume, plugin complexity, and custom functionality.

What a WordPress to PayloadCMS Migration Actually Involves

The conceptual shift from WordPress to PayloadCMS is larger than a typical platform migration. WordPress is a monolithic PHP CMS where the database, content management UI, and HTML rendering are tightly coupled. PayloadCMS is an API-first headless CMS — it manages and stores content but does not render HTML itself. The frontend (typically Next.js, Nuxt, Astro, or similar) is a separate application that fetches content from the PayloadCMS API.

This means a WordPress migration is actually two parallel workstreams:

1. CMS migration: Moving content, media, and content management capability from WordPress to PayloadCMS
2. Frontend rebuild: Building or adapting a frontend application to consume PayloadCMS's API

Some clients bring an existing frontend (a React or Next.js app that was already consuming WordPress's REST API). Others are rebuilding the frontend as part of the migration. The cost and timeline ranges in this guide account for both scenarios at the lower and upper bounds.

Pre-Migration Audit: What You Must Inventory Before Writing a Line of Code

Skipping the audit phase is the single most common cause of WordPress migration failures. Before any technical work begins, document the following.

1. Content Type Inventory

WordPress has two native content types (Posts and Pages) plus custom post types (CPTs) registered by plugins or theme functions. Run this SQL query against your WordPress database to get a full inventory:

SELECT post_type, COUNT(*) as count FROM wp_posts WHERE post_status = 'publish'

For each content type, document:

• Field list (including ACF fields, custom meta)
• Relationships to other content types (e.g., posts assigned to categories, products linked to vendors)
• Media attachments
• Custom taxonomies

2. Plugin Dependency Audit

List every active plugin and classify each as:

• Content-providing (ACF, CPT UI, WooCommerce product data) — requires data migration
• Functionality-providing (contact forms, membership, e-commerce) — requires functional replacement in the new stack
• Infrastructure (caching, security, SEO) — typically not migrated (replaced by platform capabilities)
• Obsolete — plugins active but no longer used; skip migration

A site with 30 active plugins will typically have 8–12 content-providing plugins, 5–8 functionality plugins, and the rest infrastructure or obsolete. Only the first two categories require migration planning.

3. URL Structure and SEO Audit

Export your sitemap and run it through a crawl tool (Screaming Frog or Ahrefs) to get:

• Complete URL inventory
• Inbound link profile (which URLs have significant backlink equity)
• Current meta titles and descriptions
• Canonical URL structure
• Any redirect chains already in place

This becomes your SEO preservation checklist. Every URL in the current sitemap needs either a 1:1 match in the new site or a permanent 301 redirect to the correct new URL.

Content Type Mapping: WordPress to PayloadCMS

Posts → PayloadCMS Collection

WordPress Posts map directly to a PayloadCMS Collection. The field mapping:

WordPress Field PayloadCMS Field Type Notes

post_title text required: true

post_content richText Gutenberg blocks need serialisation

post_excerpt textarea

post_status select draft/published/scheduled

post_date date

post_author relationship relates to Users collection

featured image upload relates to Media collection

categories relationship hasMany: true

tags relationship hasMany: true

post_name (slug) text unique: true

ACF (Advanced Custom Fields) fields map to PayloadCMS field types as follows:

ACF Type PayloadCMS Type

Text / Textarea text / textarea

Image upload

Gallery array of uploads

Repeater array

Flexible Content blocks

Relationship relationship

True/False checkbox

Select select

Date Picker date

Pages → PayloadCMS Collection or Globals

Simple pages (About, Contact, Privacy Policy) map to a PayloadCMS Collection with the same field structure as Posts. If you have a small number of singleton pages (homepage, global settings), use PayloadCMS Globals instead of a Collection — Globals are single-instance content objects without slugs.

WooCommerce Products → PayloadCMS Collection + External Commerce

WooCommerce products are the most complex migration scenario. Options:

1. Migrate product data to PayloadCMS and rebuild checkout functionality using Stripe, Medusa.js, or similar. Recommended for businesses where product content management flexibility matters more than checkout features.
2. Keep WooCommerce as a headless commerce backend and consume its REST API from the new frontend. No product data migration required; only frontend rebuild.
3. Migrate to a dedicated commerce platform (Shopify, BigCommerce) for products and use PayloadCMS only for marketing content. Clean separation of concerns.

Most mid-market businesses choose option 2 or 3. A full product migration to PayloadCMS with rebuilt checkout is a 12–20 week project — outside the scope of a standard CMS migration.

The Migration Process: Week by Week

Week 1–2: Schema Design and Environment Setup

• Set up PayloadCMS project with MongoDB or PostgreSQL backend
• Define collection schemas in TypeScript based on the content audit
• Configure authentication, access control, and media storage (Azure Blob or AWS S3)
• Deploy staging environment

Week 2–3: Content Migration Scripts

Write and test migration scripts to extract WordPress content via the WordPress REST API or direct database export and import into PayloadCMS.

WordPress REST API export approach (recommended for hosted WordPress):

// migrate-posts.js const axios = require('axios') const payload = require('payload')

What breaks in content migration:

• Gutenberg blocks: WordPress content stored as serialised Gutenberg block JSON does not map directly to PayloadCMS's Lexical or Slate rich text format. Custom serialisers are required for complex block layouts. Estimate 4–8 hours of engineering per complex block type.
• Shortcodes: WordPress shortcodes (`[gallery id="1"]`, `[contact-form-7]`) are not portable. Each must be identified, catalogued, and replaced with a PayloadCMS equivalent.
• Embedded media URLs: Images and files embedded in post content are stored as absolute WordPress URLs. These must be downloaded, uploaded to PayloadCMS media, and the URLs in content updated.

Week 3–5: Media Migration

Media migration is often underestimated. A mid-market WordPress site with 3–5 years of content accumulates 5,000–30,000 media items. Migration steps:

1. Export WordPress media library (via `wp media export` CLI or direct file system access)
2. Upload to PayloadCMS media collection via API, preserving original filenames
3. Update all URLs in migrated content (replace `https://oldsite.com/wp-content/uploads/...` with new CDN URLs)
4. Verify alt text and caption migration
5. Test image rendering at all defined sizes

Gotcha: WordPress generates multiple image sizes on upload (thumbnail, medium, large, custom). PayloadCMS generates image sizes defined in your collection schema. Ensure your schema defines all sizes required by the frontend before migration — re-generating sizes for 20,000 images after the fact is slow.

Week 4–6: Frontend Development or Adaptation

If building a new Next.js frontend:

• Page templates for each content type
• Dynamic routing (`/blog/[slug]`, `/[category]/[slug]`)
• Incremental Static Regeneration (ISR) configuration for content freshness
• Navigation (from PayloadCMS Global)
• Search (Algolia or PayloadCMS built-in search)

If adapting an existing React app that consumed WordPress REST API:

• Map WordPress API response shapes to PayloadCMS API responses
• Update API client calls to PayloadCMS endpoints
• Handle authentication changes (PayloadCMS uses JWT, not WordPress nonces)

Week 6–7: SEO Preservation

Redirect map implementation:

Build a redirect map from old WordPress URLs to new PayloadCMS/frontend URLs. Implement as:

• Next.js redirects (in `next.config.js`) for sites with under 1,000 redirects
• CDN-level redirects (Azure Front Door, Cloudflare) for sites with 1,000+ redirects — do not put redirect logic in the application layer at scale

Meta tag implementation:

PayloadCMS does not generate HTML meta tags — that is the frontend's job. Implement SEO fields in your PayloadCMS schema and populate them in the Next.js `<Head>` component:

// pages/blog/[slug].tsx export async function getStaticProps({ params }) { const post = await getPayloadPost(params.slug)

SEO preservation checklist:

• [ ] All published URLs return 200 or have a 301 redirect to correct URL
• [ ] No redirect chains (A → B → C; flatten to A → C)
• [ ] Canonical tags present on all pages
• [ ] XML sitemap generated and submitted to Google Search Console
• [ ] Structured data (Schema.org) preserved or improved
• [ ] Meta titles and descriptions migrated
• [ ] Open Graph tags (for social sharing) present
• [ ] robots.txt configured correctly (staging should block; production should allow)

Week 7–8: Testing and Go-Live

• Full content audit: compare page counts between WordPress and PayloadCMS
• Broken link scan on staging (zero tolerance)
• Performance baseline (Core Web Vitals via Google PageSpeed Insights)
• Editor user acceptance testing — can all editors perform their daily content tasks?
• Go-live: DNS cut-over, CDN configuration, monitoring setup
• Post-launch monitoring: track organic search impressions in Google Search Console for 4 weeks post-migration

Common Gotchas That Derail WordPress Migrations

1. Gutenberg block complexity. Sites built heavily with page builder blocks (Elementor, Divi, Beaver Builder, or Gutenberg with complex custom blocks) have content that is effectively impossible to migrate programmatically. Block-based layouts require manual reconstruction in PayloadCMS's block field structure. Budget 2–6 hours per unique block type.

2. User authentication dependencies. If your WordPress site uses membership plugins (MemberPress, WooCommerce Memberships) or custom user roles with complex permission hierarchies, user migration is a project in itself. PayloadCMS's access control is more flexible but requires rebuilding the permission model.

3. WordPress multisite. A WordPress Multisite network is significantly more complex to migrate. Each sub-site is effectively a separate CMS with shared users and media. Migrating a 5-site Multisite network is roughly 3.5x the effort of a single-site migration.

4. Scheduled content. WordPress's scheduled post feature works differently in PayloadCMS. Implement a cron job or PayloadCMS's built-in scheduled publishing feature — do not assume it works automatically.

5. Search functionality. WordPress has built-in search; PayloadCMS does not render search pages. You will need either PayloadCMS's built-in search API endpoint (suitable for basic needs) or integration with Algolia/Meilisearch for faceted search.

Cost Breakdown

Project Component Hours Cost (at £850/day)

Discovery and content audit 16–24 hrs £1,700–£2,550

PayloadCMS schema design 12–20 hrs £1,275–£2,125

Content migration scripts 20–40 hrs £2,125–£4,250

Media migration 8–16 hrs £850–£1,700

Frontend (adaptation, not rebuild) 20–40 hrs £2,125–£4,250

Frontend (full rebuild) 60–120 hrs £6,375–£12,750

SEO redirect map and implementation 8–16 hrs £850–£1,700

Testing, QA, go-live 16–24 hrs £1,700–£2,550

Total (adaptation) £8,000–£16,500

Total (full frontend rebuild) £16,000–£25,000

These are fixed-fee ranges, not estimates with contingency. The scope of each component is agreed before the project starts.

Techseria has delivered WordPress to PayloadCMS migrations for clients in the UK, UAE, and India. Our fixed-fee migration packages include content audit, schema design, full content and media migration, SEO preservation, and 30-day post-launch warranty. We provide a written migration plan before you commit to the project.

[Get a Fixed-Fee Migration Quote →](https://techseria.com/contact)