How to migrate to Payload CMS: a checklist for before, during and after the move

You’ve decided to move a site or an app onto Payload, or you’re close to deciding, and you want the whole job in order before anyone touches the data. A move to Payload has three parts. You plan it, you move the data, and you protect the live site afterwards. Payload has made the middle part easier since 16 April 2026, when it published an official migration skill for AI coding agents.

This checklist covers all three parts in 14 items, whatever you’re moving from and whichever database you choose. It’s written from the moves we’ve run on Payload, and as of September 2026 we manage 27 Payload codebases, all built on Next.js. If you came here for payload migrate and schema changes inside an existing Payload project, that’s answered in the FAQ.

• What does migrating to Payload involve?
• Before the move
• The move
• After the move
• The whole checklist on one screen
• Migrating to Payload: common questions
• What to do next

What does migrating to Payload involve?

Migrating to Payload means moving three things in order. The data model goes first, then the content, then the live site’s URLs. The model leads because Payload defines it in code, so every collection and field has to exist before any content can land in it. The content comes second, in the order its relationships allow. The URLs come last, because the old addresses carry your search traffic and every one of them needs a new home.

For example, take a company blog on another CMS with 600 posts, 12 authors, 40 categories and 3,000 images. We’ll use it through the whole checklist. Its model is four content types, its content is those 600 posts and everything they point to, and its URLs are every post, author, category and image address that search engines have indexed. The source could be WordPress, Contentful, Strapi, Sanity, Webflow or a custom database, and the database under Payload could be Postgres, MongoDB or SQLite.

Before the move

Five items come before any data moves:

1. Take an inventory of the content, and decide what stays behind
2. Export the schema only, and let a model draft the migration plan
3. Model the data in Payload
4. Choose the database
5. Map every URL

1. Take an inventory of the content, and decide what stays behind

List every content type in the old system, with a count of each, and mark what isn’t coming across. For example, the blog’s inventory might show 600 posts, of which 90 are drafts nobody has touched in three years, plus a "press" content type that stopped being used in 2021. Leaving those behind is a decision you make now, in writing, so nobody asks where they went after launch.

The inventory also tells you whether the move is still the right call. If you’re still weighing Payload against what you have, our comparisons with WordPress, Strapi, Sanity and Directus set the two side by side.

2. Export the schema only, and let a model draft the migration plan

Export the old system’s schema, meaning the structure without the content, and give it to a frontier AI model to draft the migration plan. The schema describes every content type, field and relationship, and it carries none of your customers’ data, so it’s safe to hand over. As of September 2026, models such as Claude Opus 5.5 and Fable 5.1 understand a full schema well and turn it into a proper migration plan with systematic steps.

Pro Tip: Add a small anonymised sample of the data wherever the schema can’t say what a field really is. For example, a category column holding "News" and "Technology" could be a fixed list or a set of categories editors will want to change, and a few rows make that clear.

Let the model also write scripts that find every linkage, every URL and every relation between records in the old data, which is where a model is a definite win. For example, a script can list every post that links to another post, so the links inside post bodies point to the new URLs on launch day. When we do migrations, the plans go out to the client for sign-off, and working them with a model gives us several ways of checking every point of entry and every breakage that could happen.

Past business decisions often don’t look clean in data, and a model translates what it sees. On one of the migrations we were looking at, the data looked simple and the relations were all there, but there was more business logic behind them, and the model couldn’t see it. So someone who knows the business reads the mapping before it’s signed off.

The model doesn’t have to stop at the plan. It can carry on through the move with Payload’s own skill (item 6) and into the ongoing development of the new build. How far you take it is your team’s call.

3. Model the data in Payload

Write the Payload collections, globals and fields before importing anything, and settle each field’s type while the data is still in the old system. Payload gives you text, rich text, relationship, upload, select, array, group and blocks fields, among others. The choice that matters most is between a select field and a relationship. Payload’s migration skill calls it "the most common migration mistake", because values that look fixed, such as categories and tags, usually need to be a collection editors can change.

For example, the blog’s 40 categories become a Categories collection with a relationship from each post, and its "status" field stays a select with draft and published. If several brands or regional sites are coming across into one install, decide on tenancy now, before any content lands. Our guide to Payload multi-tenancy covers how to model the tenant first. Once the model is in Payload, it can grow into things the old system couldn’t hold, and our Payload use cases show where teams take it.

4. Choose the database

Settle the database while you write the model, because it changes how you manage the model after launch. Payload runs on Postgres, MongoDB or SQLite through its database adapters. On Postgres and SQLite, every change to a collection after launch needs a schema migration, while MongoDB mostly doesn’t.

For example, if the blog will add fields every month after launch, a relational database means a migration for each change, and your deploy process has to run them. The choice also moves the running cost, since database hosting is part of the bill, and our breakdown of Payload pricing covers what that adds up to.

5. Map every URL

Build a table of every old URL and the new URL it becomes, before the build starts. Google’s guide to site moves with URL changes starts from a mapping of old URLs to new ones, and permanent redirects keep the ranking signals of the old pages.

For example, the blog’s posts might move from /2023/04/post-title to /blog/post-title, its categories from /category/news to /blog/category/news, and its images to new file paths entirely. A script can pull every old URL from the sitemap and the database, so no address depends on someone’s memory.

The move

With the plan signed off and the model written, the data can move in five steps:

1. Design the collections with Payload’s cms-migration skill
2. Import in dependency order
3. Convert rich text and move media
4. Pick the import route
5. Dry-run on a copy, then freeze and cut over

6. Design the collections with Payload’s cms-migration skill

Payload’s cms-migration skill is an official set of instructions for AI coding agents that turns your source data into Payload collection configs through a conversation. It lives in the payloadcms/skills repository alongside the general payload skill, which covers collections, fields, hooks, access control and the database adapters for the build itself. You install both with one command:

npx skills add payloadcms/skills

The skill asks you for a sample of your data as JSON or CSV, or a description of your schema. It proposes a collection config, explains its field choices, and asks when a field could go more than one way. You confirm or change the config, then it asks for the next content type. Only once every collection is confirmed does it move on to the import, covering the order, how source IDs map to Payload IDs, media, and rich text, and it offers to write the seed script. Its reference file carries field mappings for WordPress, Contentful and Strapi. For example, an ACF flexible content field in WordPress becomes a blocks field in Payload, and a Strapi dynamic zone does the same.

In practice, the plan from item 2 goes into the conversation with it, so the skill works from decisions you’ve already signed off.

7. Import in dependency order

Import the content that nothing depends on first, then the content that points to it. For the blog, that means media, then authors, then categories, then posts, because each post points to an author, its categories and a featured image. Keep a table of every source ID and the Payload ID it becomes, since a post’s author field has to point to the new author record, not the old ID.

8. Convert rich text and move media

Payload stores rich text as Lexical JSON, so HTML from the old system has to be converted on the way in. Payload’s convertHTMLToLexical does the conversion, and it deliberately leaves out <img> tags, because it can’t know which upload collection an image belongs in. So images inside post bodies need their own step. Upload each file to your media collection, then insert an upload node where the image sat. If your content comes from an older Payload project on Slate, Payload has a separate Slate to Lexical migration.

For media generally, decide whether files are downloaded and re-uploaded, or kept at their existing URLs. For example, the blog’s 3,000 images are re-uploaded so they sit in the new media collection with their alt text, and the old image URLs go into the redirect map from item 5.

9. Pick the import route

There are two routes, and a move often uses both. The first is a script on Payload’s Local API, which runs inside Node with full access to your collections, and Payload lists seed scripts as one of its common uses. A script suits anything with logic in it, such as ID mapping, rich-text conversion and relationships.

The second is Payload’s official Import Export plugin, which imports and exports CSV and JSON from the admin panel, with a preview before import. It maps foreign column names onto Payload fields, and by default it runs imports through Payload’s jobs queue, so a job runner has to be configured (jobs.autoRun) or the import sits in "pending" and never finishes. For example, a spreadsheet of 2,000 products with columns named for the old system can be mapped and imported without a line of script. Older forum answers say the plugin only exports, and as of September 2026 its docs list import as a core feature.

10. Dry-run on a copy, then freeze and cut over

Run the whole import against a copy of the new database first, and count what came across. Compare the number of records per content type in the old system and in Payload, and open a sample of each by hand. For example, 600 posts in, 510 posts out, and 90 drafts deliberately left behind, which matches the inventory from item 1.

When the counts match, agree a content freeze with the editors, run the import for real, and switch the domain over. The freeze is what stops a post published in the old system on cutover day from being lost.

After the move

Once the new site is live, four items protect the search traffic and the data the old site built up:

1. Redirect every old URL, and crawl both sites
2. Check the data behind every page
3. Watch Search Console for four weeks
4. Hand over

11. Redirect every old URL, and crawl both sites

Put the URL map from item 5 in place as permanent 301 redirects, then crawl the old site and the new one and compare them. Google says 301 and other permanent redirects don’t cause a loss in PageRank. Payload’s Redirects plugin stores redirects in the admin, and your frontend reads and serves them.

The crawl comparison checks each old URL for the right status code, title and canonical on the new site. On a WordPress site we ported, the first comparison flagged hundreds of mismatches that all turned out to be flaws in the crawler itself, and the full account is in our Payload vs WordPress guide.

12. Check the data behind every page

A page that looks right can still be missing its author, its categories or half its images. Check counts per collection, confirm every relationship points to a record that exists, and look for media that nothing links to. For example, a query for posts with no author finds the ones whose author ID didn’t map in item 7.

13. Watch Search Console for four weeks

Watch the new property in Search Console daily for the first week and weekly after that. Google’s site-move guide says to check each property separately in Search Console, using the indexing and Sitemaps reports, and warns that for a medium-sized site the move can take a few weeks or more to settle. For example, a spike in 404s in week one usually means a pattern of old URLs missing from the redirect map, and one new redirect rule fixes the whole pattern.

14. Hand over

Train the editors on the new model, and write down what moved, what didn’t, and why. The inventory, the signed-off plan and the URL map are most of that record already, so the handover is putting them in one place with the decisions and their dates. For example, the blog’s record says the 90 stale drafts and the retired press section were left behind on purpose, and when that was decided. If you’re planning a move and would like a hand with it, our Payload CMS development team takes migrations from the plan to the handover.

The whole checklist on one screen

What to do next

Start with the schema. Export it from your current system, add a small anonymised sample where the fields are ambiguous, and let a model draft the plan. Then model the data in Payload, import in dependency order, and redirect and crawl before you call the move done. If you’d like the wider picture before you start, our Payload CMS guide covers the platform in full, and you can install Payload’s skills today with npx skills add payloadcms/skills.

References

• payloadcms/skills repository
• Payload cms-migration skill
• Payload cms-migration field reference
• Payload docs, configuration overview
• Payload docs, fields overview
• Payload docs, database overview
• Payload docs, migrations
• Payload docs, converting HTML to Lexical
• Payload docs, Slate to Lexical migration
• Payload docs, Local API
• Payload docs, custom components and the import map
• Payload docs, Import Export plugin
• Payload docs, Redirects plugin
• Google Search Central, site moves with URL changes

All links checked and active as of 25 September 2026.