Migrating off Payload: how to leave cleanly

A disclosure before anything else: WAYF is a Payload partner agency and a top contributor to the project. We build on Payload daily, we recommend it often, and most of the migration library on this site describes moving onto it.

This guide is for the day the decision goes the other way. A parent company standardizes its properties on one vendor. Procurement consolidates contracts. A platform choice gets made above the team that runs the website, and there is no reverting it. Teams in that position get a partner who runs the exit properly; nothing on this page argues for staying. Part of why WAYF recommends Payload in the first place is that leaving it is genuinely possible: the license is MIT, the data sits in your own database, and the code is yours. What follows is that exit, written down.

What you are actually holding

Payload’s documentation describes an “open-source TypeScript codebase you own and deploy anywhere.” Concretely, a Payload installation means:

• Your database. Content lives in MongoDB, Postgres, or SQLite — whichever your team pointed Payload at. There is no vendor database to petition; your DBA can read every row today.
• Your media. File metadata sits in the database; the binary files sit on your own disk or your own S3-compatible storage, depending on how uploads were configured.
• A content model in TypeScript. Every collection, field, block, and relationship is declared in code. That configuration is the field-by-field specification of the migration — the mapping document other exits have to reverse-engineer from an admin UI already exists in your repository.
• Three APIs. REST and GraphQL endpoints are auto-generated for every collection, and the Local API runs the same operations directly in Node with no HTTP hop — Payload’s own docs frame it as the tool for migration scripting.

What comes out as data

The official @payloadcms/plugin-import-export — out of beta since v3.85.0 — exports any collection as CSV or JSON from the admin UI, and the JSON path preserves nested structures, arrays, and Lexical rich text exactly as stored. For a straightforward estate, that plugin plus a media copy is most of the extraction. Two caveats from the plugin’s own documentation are worth knowing before you rely on it: virtual fields do not round-trip, and export jobs need the jobs queue configured to run, or they sit pending.

For anything the plugin’s shape doesn’t fit — selective exports, live deltas during a long cutover, transforms applied in flight — the Local API is the standard path: a Node script iterates collections, applies your mapping, and writes to the destination’s import surface.

Where the engineering sits

Most of the budget sits in the transform, and it concentrates in four places:

• Rich text. Payload stores Lexical content as a JSON tree of typed nodes — paragraphs, headings, lists, links, uploads, and blocks. The destination will want its own format: HTML, Markdown, Portable Text, or a proprietary structure. Paragraphs and headings convert mechanically; embedded uploads and custom blocks need explicit decisions, because a block your team designed has no automatic equivalent anywhere else.
• Relationships. Payload references documents by ID. Those IDs will not survive the move, so the load keeps a mapping table and resolves references against the destination’s new identifiers — the same discipline as any CMS migration, run in reverse.
• Logic in code. Hooks, access control, and validation live in your Payload config. None of that exports as data; it gets re-expressed in whatever the destination platform uses for the same jobs. Budget this as design work, because the destination’s model for permissions and workflow will not mirror yours one-to-one.
• Localization. If the estate runs multiple locales, the locale structure needs its own mapping — systems disagree about whether a translation is a field variant, a linked document, or a separate tree.

The website usually stays

The most common relief in a Payload exit: the site itself is not the thing being replaced. When Payload runs headless behind a front end your team owns, the exit swaps the content backend while the rendered site, its design system, and its URLs stay in place. The cutover becomes a data-source change verified by parity testing — no redesign, and no redirect project unless the organization chooses to change URLs at the same time. Even where Payload and the front end share one Next.js application, the front-end code remains yours to point at the new backend.

Where the destination is a coupled platform that insists on rendering the site itself, that is a replatform in the full sense — and the same discipline in our replatforming service applies, with the URL inventory and redirect map back on the table.

Running the exit

An exit run properly looks like every migration we publish, with the direction reversed: inventory the model from the TypeScript config, agree the mapping into the destination’s schema, transform with fidelity checks so silent field loss shows up in a report instead of in production, load idempotently so the import can run repeatedly before cutover, and verify parity before anything switches. Contributor-level knowledge of Payload’s internals is what it sounds like: when something in the export behaves unexpectedly, we know where to look, and we have direct access to the maintainers.

The Payload migration page is where to tell us what you are running and where the organization is heading. A free consultation and a scoped, fixed quote come before any commitment.

FAQ

1. Can we export everything from Payload?

   Content and media, yes: the database is yours, the official import-export plugin dumps collections as JSON or CSV with Lexical rich text preserved as stored, and the REST, GraphQL, and Local APIs cover anything a script needs. Two things do not come out as data: virtual fields do not round-trip through the plugin, and logic that lives in hooks and access control is code, so it gets re-expressed on the destination platform rather than exported.

2. Do we lose our website when we leave Payload?

   Usually not. When Payload runs headless behind a front end your team owns, the exit swaps the content backend while the site, its design, and its URLs stay in place. The cutover is then a data-source change with parity testing, and there is no redirect project unless you choose to change URLs at the same time.

3. Why does a Payload partner publish an exit guide?

   Because the ownership claims behind the recommendation — MIT license, your database, your storage — are proven at the exit, and a partner who publishes the exit path stands behind them. When an organization's decision goes the other way, the same contributor-level knowledge of the codebase is what makes the move clean.

4. How long does a migration off Payload take?

   The inputs set the calendar: how many collections there are, how much rich text and how many custom blocks the content carries, the integration list, and how many locales it runs in. We scope it per project — the first conversation is a free consultation, and a fixed written quote follows discovery.

Sources

• Payload Docs, What is Payload?
• Payload Docs, Database overview — MongoDB, Postgres, SQLite adapters
• Payload Docs, Local API overview
• Payload Docs, Rich Text (Lexical) overview
• Payload Docs, Import Export plugin
• Payload, Import/Export plugin out of beta (release v3.85.0)
• Payload Docs, Uploads overview
• Figma, Payload joins Figma (June 2025)