How to migrate from Contentful to Payload without losing content or editors
If your team wants to own its CMS, run it inside a Next.js app and keep the code under MIT, the migration is a schema rebuild plus a scripted content import, not a file copy. The Contentful space export carries content types, entries, assets, locales, webhooks and editor interfaces as JSON, but it does not carry roles or permissions, so access rules and editor memberships must be recreated in Payload's own authentication and access control. Plan for both halves of the work from the start.
This work usually falls to frontend and platform engineers, paired with a content owner who knows which fields editors actually use. The engineers translate each Contentful content type into a Payload collection defined in TypeScript, then write import scripts that call Payload's Local API or REST API to create entries and upload assets. The content owner checks the mapping on a staging copy, especially references, rich text, localized fields and draft status, because these are where imported content most often looks correct in a script and wrong on the page. Confirm with your team whether published-only content or drafts also need to move.
Effort and risk depend mostly on how many content types you have, how heavily rich text and references are used, and how much frontend code reads the Contentful API directly. Build the new schema and import on a staging database first, run both systems in parallel until editors sign off, and keep the Contentful export as a dated backup. Ask your implementation partner or internal team to estimate the effort from a content model inventory, since no general figure applies to every space. Confirm the current Payload release line and its database support against the Payload GitHub repository before you pin versions.
Which Contentful capabilities map cleanly to Payload
This table maps each Contentful capability to its Payload equivalent and marks it clean, needs rework or gap. Read the status column first, then check each row against your own space, because export scope and plan features vary. Most content modeling and editing moves cleanly, while roles, webhooks and delivery plumbing need rebuilding in code or configuration.
| Contentful capability | Payload equivalent | Status |
|---|---|---|
| Content types | Collections and fields defined in TypeScript code, with types generated automatically | Clean |
| Entries | Documents in collections, imported by scripting through Payload's local or REST API | Clean |
| Assets | Upload-enabled collections storing files in local or cloud storage you configure; re-upload from the export's asset files | Needs rework |
| Locales | Built-in localization configured in code; field-level translations must be remapped from Contentful's locale codes | Needs rework |
| Drafts and preview | Versions and drafts, plus live preview; confirm publish and scheduling rules match your editorial workflow | Needs rework |
| Roles and permissions | Field-level access control and collection access functions written in code; the Contentful export does not carry roles, so rebuild them | Gap |
| Webhooks | Document and field hooks run in your app, but Contentful webhook endpoints and credentials must be reconfigured by hand | Gap |
| Editor interfaces | Customizable React admin panel and Lexical rich text editor; Contentful appearance settings are not carried over | Needs rework |
| API delivery | Auto-generated REST and GraphQL endpoints from collections, served from your Next.js app; caching and CDN are your responsibility | Needs rework |
What the Contentful export carries into Payload and what you rebuild
The Contentful CLI space export gives you the content model and content as JSON, plus asset files, but it does not carry access rules, webhook credentials or editor customizations. The cards below separate what arrives in the export from what your team must design, configure and test in Payload before cutover.
Content model and entries as JSON
The space export captures the published content model, including content types, entries and locales, as JSON. Use it as the blueprint for Payload collections and fields defined in code. Map each Contentful content type to one collection, then decide how references, localized fields and rich text fields translate. Check that unpublished drafts are handled deliberately, because the export covers the published model and content.
Assets and asset files
The export can download asset files alongside asset metadata, so media does not have to be re-fetched by hand. Confirm which assets are embargoed or access-restricted in your space, because those may need separate handling. Payload stores uploads through its upload configuration, so decide where files will live, then script the asset records and file references into the new media collection and verify each relationship after import.
Webhooks are exported, targets are not
The export includes webhook definitions, but the endpoints and any signing secrets they depend on must be reviewed. Many webhooks point at build hooks, search indexers or preview deployments that belong to the old stack. Inventory each webhook, decide which Payload hook or external job replaces it, and move the credentials into your own secret store. Test publish events end to end before you switch the frontend.
Roles and permissions must be rebuilt
Roles and permissions are not exported, so every Contentful role must be redesigned as Payload field-level and collection-level access control. Write down who can create, publish and edit each content type today, then express those rules as access functions in code. Review them with editors, because the old role names rarely map one to one onto Payload permissions.
Editor UI customizations are rebuilt in React
Editor interfaces in Contentful are configured through the space, and they do not carry over as working Payload components. Identify which field widgets, layouts and extensions editors depend on, then rebuild the necessary ones with Payload's customizable React admin panel. Keep this list short at first, and prioritize the customizations that editors use every day.
User accounts are a separate identity task
Users are not a content export. Plan the move of admin and customer identities as its own workstream, including password reset, multi-factor setup and deactivation of former Contentful members. Payload includes built-in authentication, so decide which accounts are created in the CMS, which need federation with your identity provider, and how you will confirm that no inactive user keeps editing access.
How Contentful content types become Payload collections in code
Each Contentful content type becomes one Payload collection, defined as a TypeScript config file in your Next.js app rather than a model built in a web console. Field definitions in the type (short text, number, boolean, date, media, reference, object and rich text) map to Payload fields of matching kinds, and the slug of each type becomes the collection slug that your API calls will use. Reference fields that point to a single entry become relationship fields, and reference lists become hasMany relationships with an explicit target collection. Contentful rich text becomes a Lexical rich text field, so embedded entries and inline links need to be expressed as blocks or relationships in the new schema, which is the step most likely to need hand conversion. Confirm the exact field-type list and the rich text options against the Payload documentation for the version you install, since Payload's own releases change the field API.
Entries and assets are written in through Payload's Local API or REST API rather than an import wizard, so the script you write is the migration record. Read the Contentful space export JSON, create assets first so their IDs can be referenced, then create entries in dependency order and keep a map from each Contentful entry ID to the new Payload ID. Decide before the first run how Contentful locales map onto Payload localization, because Payload's localized fields store per-locale values and changing the locale list later means rewriting data. Likewise decide whether imported entries land as published or as drafts; Payload's versions and drafts feature stores draft state alongside each document, and a script that writes without the draft flag will publish everything. Generated TypeScript types then come from the collection config, which replaces the hand-maintained content model files many Contentful projects keep alongside their API client. Run a dry run against a staging database and compare entry counts per content type before pointing the frontend at it.
The migration sequence from inventory to decommission
This sequence moves a Contentful space into a Payload collection model inside a Next.js app in controlled stages, so each step produces a checkable artifact before the next one depends on it. Contentful stays the source of truth until the cutover step is complete and verified.
Inventory content types, locales and integrations
Export the space with the Contentful CLI and list every content type, field, validation, locale, reference, webhook, editor interface and downstream consumer of the delivery API. Roles and memberships do not come out of the export, so record them by hand from the Contentful web app. Your team owns the inventory, and an engineer who knows the Next.js frontend should review it. The step is done when you have a field map covering every content type and a written list of integrations that read from or write to the space.
Define a pilot collection in code
Choose one content type with a representative spread of fields, such as a rich text body, a reference, a media field and at least one localized field. Define it as a Payload collection in the Next.js app, generate the TypeScript types, and choose PostgreSQL or MongoDB for the database before any data moves. Test drafts and the admin panel against the collection. The output is a pilot collection in version control, a documented database decision and a short list of field types that needed a workaround.
Script a verified import of the pilot entries
Write an import script that reads the space export, maps each Contentful entry to a Payload document through the Local API or REST API, and uploads assets to your media storage. Keep the original Contentful entry IDs in a stored field so references can be resolved in a second pass. Run the script against a staging database and keep a log of created, skipped and failed records. The step is done when the pilot entries match the source on a sample check and every failure has a recorded reason.
Migrate the remaining collections and locales
Repeat the pattern for each remaining content type, starting with those that other types reference, and enable Payload localization for each locale from the inventory. Resolve references in a second pass once every target collection exists. Re-run the full import against a fresh staging database to confirm it is repeatable. The output is a complete import log, an exception list for content that needs manual correction, and a reconciled count of entries per locale.
Run Contentful and Payload in parallel
Point a staging or preview build of the Next.js frontend at Payload while production still reads Contentful. Compare rendered pages from both sources, check draft and live preview behavior for editors, and confirm access control rules match the roles you recorded. Editors should work through the new admin panel on a test copy of real content. The step is done when the differences list is empty or each difference has an accepted fix.
Cut over delivery, webhooks and editors
Switch production reads to Payload, rebuild webhooks for cache revalidation and any downstream consumers against Payload's hooks or your own endpoints, and move editor accounts into Payload's built-in authentication. Freeze Contentful writes for a short agreed window and run a final delta import so no edits are lost. Keep a written rollback plan that names the previous frontend configuration and the Contentful read path, and confirm who can execute it. The output is a signed-off cutover checklist and a rollback procedure that was tested before the window opened.
Decommission the Contentful space after export
After the production system has run cleanly, take a final export, archive it with the asset files in storage you control, and record the export checksum and retention location. Remove API keys, revoke webhooks and cancel or downgrade the subscription according to your contract terms, which you should confirm with Contentful before acting. The step is done when the archive is verified, access is removed and the decommission record is filed with the owners of the content.
Choosing PostgreSQL or MongoDB for Payload
If your organization already operates PostgreSQL with tested backup, failover and patching routines, PostgreSQL is usually the lower-friction choice for Payload. Your database administrators keep the same tools, monitoring and recovery runbooks, and your auditors already have evidence paths for the platform. Payload's content is stored in a relational schema that your team can query, report on and back up with the same procedures used for other business systems.
- Operational reuse: Existing point-in-time recovery, replication and connection pooling apply without a second database discipline.
- Backup scope: Dump and restore procedures for the CMS sit alongside the rest of your PostgreSQL estate, which simplifies restore testing.
- Reporting access: Analysts and content operations can read the database with standard SQL tools, subject to your access policy.
- Hosting choice: You decide whether PostgreSQL runs on a managed cloud service or on your own servers, and that choice drives cost and patching responsibility.
- Cost driver: Recurring cost depends on your database hosting model, storage growth and the staff time to maintain upgrades.
Before committing, confirm with the Payload repository which PostgreSQL adapter and version the current release supports, and confirm your own restore time against a copy of the database.
If your platform team already runs MongoDB replica sets for other applications, Payload's MongoDB support lets you reuse that operational knowledge. The document model maps naturally to Payload's nested fields, blocks and localized values, so the storage shape stays close to the content structure defined in code. This path works best when MongoDB administration is already a routine skill in your organization rather than a new responsibility.
- Existing expertise: Replica set management, index tuning and monitoring stay with the team that already owns MongoDB.
- Document fit: Nested block layouts and localized fields are stored without heavy join logic, which can simplify early development.
- Backup tooling: Backups use your existing MongoDB strategy, but you must test restores of Payload's collections, including versions and drafts, before go-live.
- Migration tooling: Schema changes follow Payload's migration approach for MongoDB, so plan upgrade rehearsals in a non-production environment.
- Licensing check: Confirm the license and support terms of the MongoDB distribution you run, since these are separate from Payload's MIT license.
Confirm the supported MongoDB driver and server versions in the Payload repository before you pick a version, since compatibility can change between Payload releases.
SQLite suits development environments, previews, proofs of concept and small internal sites where one application instance writes to one file. It removes the need to provision a database server, which keeps local setup and continuous integration simple. Treat it as a deliberate scope decision rather than a shortcut, because a single-file database has different backup, concurrency and scaling characteristics from a networked database server.
- Simple setup: A developer can run the CMS and its database from the same project without installing a separate service.
- File-level backup: Backing up the database means copying a file, which must be done while the application is quiet or with a consistent snapshot method.
- Concurrency limits: Multiple application instances writing to a shared file are a poor fit, so confirm your deployment topology before choosing it.
- Promotion path: Plan a migration to PostgreSQL or MongoDB before production traffic and editorial volume grow, and test that migration with real content exports.
- Illustrative case: A content team's staging site might run on SQLite while production uses PostgreSQL, but the two must be kept in step through the same schema definitions.
Confirm with the Payload repository which SQLite adapter version applies to your release, and document the promotion steps before you rely on SQLite for anything beyond testing.
What drives the cost and duration of this migration
This table lists the factors that most change the effort of moving a Contentful space to Payload, with the reason each one matters and how to keep it under control. Read it before asking for a quote, since the same drivers appear in any written scope. The main takeaway is that content model size, rich text and the number of frontends usually matter more than the raw entry count.
| Driver | Why it changes cost or effort | How to keep it down |
|---|---|---|
| Content types and fields | Each content type becomes a code-defined Payload collection with typed fields, so every type needs a schema decision, a mapping and a test pass. | Trim unused types and fields from the export before mapping, and merge near-duplicate types into one collection with a type field. |
| Locales | Payload localization is configured per field, so each localized field must be mapped, and fallback rules must be set and verified for every locale. | Confirm the locale list with editors early and drop locales that have no live content. |
| Entry and asset volume | Scripted imports through Payload's API run record by record, and asset files must be re-uploaded to the new media storage, so volume drives run time and storage transfer. | Import in batches, test on a subset of entries first, and separate asset transfer from entry import so each can be rerun. |
| Rich text complexity | Contentful rich text and embedded entries or assets must be converted into Lexical content or blocks, and nested embeds are the most common source of rework. | Inventory embedded entries and custom node types before migrating, and agree on a limited set of blocks for the first release. |
| Number of frontends and webhooks | Each frontend that reads Contentful needs its data layer rewritten against Payload's API or local API, and each webhook must be rebuilt as a hook or external job. | List every consumer of the Contentful API and every webhook target, then retire the ones no longer used. |
| Editorial workflow and preview | Drafts, versions, approval steps and live preview must be configured and tested with editors, and access rules must be rebuilt because the export does not carry roles. | Write down the current publish and review steps first, and limit the first release to the workflow editors use daily. |
| Database and hosting choices | Choosing PostgreSQL, MongoDB or SQLite and the hosting target changes backup, scaling and operations work, and each choice carries its own setup and monitoring scope. | Decide the database and hosting target before scoping, and ask the implementation partner to state who runs backups, upgrades and media storage. |
What usually goes wrong when moving from Contentful to Payload
Most failed Contentful-to-Payload moves fail on details the export does not carry, not on the core content model. The cards below cover the gaps that tend to surface after cutover and the checks that catch them before editors notice.
Assuming the export carries roles
The Contentful CLI space export covers the published content model, content, assets, locales, webhooks and editor interfaces, but roles and permissions are not exported. Teams that expect editor access to arrive intact in Payload often find that access rules, including field-level and document-level restrictions, must be written again. Inventory every role and its permissions in Contentful before export, then define the equivalent access control in Payload's collection and field configuration and test it with a real editor account.
Losing asset links and embargoed files
Asset records can import while the underlying files fail to download, leaving entries that point at missing media. Embargoed or access-restricted assets are the usual cause, since the download can be refused for some files. Before cutover, run a script that compares every asset ID referenced by an entry against the uploaded Payload media documents, and keep a list of any file that could not be fetched so it can be resolved by hand.
Schema drift during the parallel run
If editors keep working in Contentful while the Payload build runs, content types change and the code-defined collections fall behind. Field renames, new required fields and changed reference targets then break the import script on the second or third run. Freeze schema changes in Contentful for the migration window, or record each change in a shared log and apply it to the Payload collections before every re-import.
Locale fallback gaps
Contentful and Payload both support localized fields, but fallback behavior differs by how each locale is configured. A field left empty in a secondary locale may show blank text on the site instead of the default-locale value. Compare fallback settings for each locale in both systems, then render every locale for a sample of pages in the new frontend to confirm that gaps show the content you intend.
Broken preview after cutover
Editors rely on preview to check drafts before publishing, and Contentful preview URLs and webhooks usually point at the old stack. Once traffic moves, a preview link that still references Contentful or an unconfigured Payload draft route shows stale or empty content. Configure Payload's drafts and live preview in staging, change every preview and publish webhook to the new endpoints, and test a draft edit end to end before the cutover date.
Running Payload's v4 beta in production
Payload's v4.0.0 line is still in beta, and the newest releases can change faster than a stable line. The releases page lists v3.91.0, released on October 15, 2026, and v4.0.0-beta.2, published on October 16, 2026. Pin the exact Payload version in your lockfile, choose the stable v3 line for production unless you have verified a v4 upgrade path, and review the releases page before each upgrade.
How the migration changes by starting point
A small space with a handful of content types and a modest number of entries is the most forgiving case. The export is small enough to review by hand, and a single developer can usually define every collection in code within one working cycle. Most of the effort goes into the Next.js application and the frontend queries rather than the data itself. Because the content volume is low, a short parallel run is often practical before the cutover.
- Schema review: Compare each Contentful content type with a Payload collection or global, and decide early whether any type is really a single settings object.
- Entry scripting: A few hundred entries can be scripted through Payload's local API in one pass, with a dry run first against a throwaway database.
- Assets: Download asset files from the export and upload them through the Payload upload collection, keeping original filenames where URLs depend on them.
- Frontend cutover: Switch the Next.js queries to Payload and remove the Contentful SDK, which is usually a contained change.
- Hosting choice: Pick the database and deployment target once, since a small site rarely justifies a separate operations stack.
Before committing, confirm with the team which webhooks and preview links depend on Contentful, because these are easy to forget in a small project.
A large space with many locales, many editors and years of accumulated content needs more planning before any code is written. Locale fallback rules, publishing workflows and editor roles tend to carry the most risk. Payload's localization and drafts features cover the building blocks, but the mapping of Contentful locales and fallback behavior must be verified field by field. Migration is usually staged by content area rather than in one run.
- Locale inventory: Record every locale, its fallback chain and which fields are localized, since the export carries locales but not every editor habit.
- Phased import: Move content in batches by content area, validating each batch against the source before the next begins.
- Editor roles: Roles and permissions are not included in the space export, so access rules must be designed again in Payload's field-level and collection access control.
- Draft and publish states: Map Contentful's published and changed states to Payload versions and drafts, and test scheduled publishing separately.
- Database sizing: Confirm with the platform team how PostgreSQL or MongoDB will handle the volume, including backups and restore tests.
Ask the content leads to review a sample of localized entries in the new system before any editor is moved over.
A team that already builds its frontend in Next.js has the most direct path, because Payload installs into an existing Next.js /app folder and shares its code, types and deployment. Types generated from collections can feed the frontend directly, which removes a separate client layer. The main decisions are about where the CMS runs and how preview traffic reaches it, not about the frontend framework.
- Shared codebase: Install Payload alongside the existing app so the admin panel, API routes and frontend build from one repository.
- Generated types: Use the TypeScript types generated from collections in place of the Contentful client types.
- Live preview: Rebuild preview routes against Payload's live preview feature and test them with draft content.
- Deployment target: Choose between a self-hosted server, Vercel or Cloudflare Workers with R2 and D1, based on where the team already operates.
- Auth boundary: Decide whether editors and customers share one authentication model, since Payload includes built-in authentication.
Confirm the Next.js version and deployment constraints with the team before choosing the hosting target, since they determine what the install looks like.
A team whose frontend runs on another framework, a mobile app or a set of separate services needs Payload to act as an API layer rather than as part of the page code. The CMS still installs into a Next.js app, so this team takes on a second application purely for content, plus an API contract that every client depends on. Scope grows because each consumer's queries, caching and preview behavior must be rebuilt.
- API contract: Define the REST or GraphQL endpoints that each consumer uses and version them before rewriting queries.
- Consumer inventory: List every client that reads Contentful, including mobile apps, scheduled jobs and search indexers.
- Caching and webhooks: Rebuild cache invalidation and publish webhooks in the new system, since Contentful webhooks are not carried over as credentials.
- Preview paths: Give each frontend its own preview flow, which can take longer than the data migration itself.
- Parallel running: Run both sources for a period so each consumer can switch independently.
Confirm with each consuming team which endpoints and webhook payloads they depend on, because those contracts set the real scope of the project.
Questions buyers ask before moving from Contentful to Payload
What does a migration from Contentful to Payload cost, and what drives it?
The cost depends mostly on the size and shape of the content model, the number of entries and assets, how many locales you run, and how much frontend code has to be rebuilt in Next.js. Payload itself is MIT licensed, so there is no license fee for the CMS. The recurring lines are hosting, the PostgreSQL or MongoDB database, media storage, CDN, backups and the team time to maintain the application. The one-time lines are the migration scripts, the collection rebuild, testing and any rebuild of webhooks and roles. Ask any implementation partner for a quote built from a written scope that lists each of these lines separately.
How long does a Contentful to Payload migration take?
Timing is driven by the number of content types, how much rich text and reference transformation is needed, the volume of assets to re-upload, and how many locales and channels must be verified. A small space with a few content types and one frontend is far quicker to move than a multi-brand space with years of entries. No duration is set for this page, so ask for a timeline in the written scope, with milestones for collection definitions, script runs, a staging cutover and a frontend switch.
Is Payload MIT licensed, and where should I verify it?
Yes, Payload is an MIT-licensed CMS. The license text and the project's own statements sit in the Payload GitHub repository, and that is the place to confirm current terms before you commit. Release history, including the most recent versions and the v4.0.0 beta line, is listed in the Payload GitHub releases page. Check both before you pin a version, because a beta line may change APIs before a stable release. Your legal team should also review the licenses of any plugins and frontend packages you add.
Which database should I choose for Payload, PostgreSQL or MongoDB?
Payload supports MongoDB, PostgreSQL and SQLite, so the choice is a platform decision rather than a feature gap. PostgreSQL is usually the better fit when your organization already runs relational databases, needs strong backup and reporting tooling, or wants to share data with other systems. MongoDB suits teams that already operate it and prefer document storage. Confirm the adapter you plan to use against the Payload documentation for your version, and test backup and restore on the database you select.
Can our in-house team do the migration without a partner?
A team that already knows TypeScript, Next.js and a SQL database can do the work in house, and Payload's code-defined collections make the model easy to review in version control. The hard parts are usually the content transformation, the asset re-upload, the rebuilt editorial workflow and the cutover plan, which need someone who has done it before. Before deciding, count the people who can own the collections, the import scripts and the on-call duties after launch. A partner can take a fixed scope with written deliverables while your team keeps ownership of the result.
What does our team need to provide during the migration?
You need a named owner for the content model, a developer who can review the TypeScript collections, and someone with access to the Contentful space and the hosting accounts. Editors should be available to check rich text, references and drafts in staging. Security or compliance staff should review access control, authentication and where data is stored. Ask the implementer to list these roles and hours in the written scope so there are no surprises mid-project.
Does the Contentful export carry over everything, including roles and webhooks?
The Contentful CLI space export backs up the published content model, content, assets, locales, webhooks and editor interfaces as JSON, and can download asset files. Roles and permissions are not exported, so Payload's access control and user accounts must be designed and rebuilt by hand. Use the Contentful CLI documentation to confirm what your version exports, and plan to recreate webhook targets and any draft or embargoed assets separately.
How DeployOpen scopes and runs a Contentful to Payload migration
DeployOpen plans, implements, integrates, hardens, backs up and documents self-hosted platforms inside the client's own infrastructure, including the cloud account or data center where the Payload application and its database will run. For a Contentful to Payload move, the written scope usually has to settle a few decisions first: which database engine (PostgreSQL or MongoDB) the team will operate, where media files will live, which Next.js hosting target will serve the application, and which content types are in and out of the first cutover. Most engagements are fixed scope, so those decisions, the deliverables and the acceptance checks are agreed in writing before any build work starts. A quote follows from that written scope, which means the more precisely the content model inventory, locale list and integration points are described up front, the more closely the quote can track the actual work.
Several items in a Payload migration are easy to underestimate and are worth naming in the scope document. Collections, globals and field-level access rules have to be rewritten in code from the Contentful content types, and the team should confirm who owns that schema review. Scripted imports through Payload's API need a defined rollback path, a reconciliation report comparing entry counts per locale, and a plan for asset re-upload and reference rewriting. Drafts, versions and live preview need to be tested against the editorial workflow the team actually uses. Each of these is a deliverable that can be listed, scoped and accepted. Ask any provider, DeployOpen included, to show how each one maps to a named deliverable instead of a general statement that the migration is covered.
Ongoing work after cutover is priced separately. Upgrades to Payload, security patching for the Next.js application and database, backup verification, and monitoring are recurring items that a retainer can cover, and a retainer scope should state response expectations in writing rather than assume them. Compliance readiness work, such as producing evidence for access control and change management, is also available, but DeployOpen prepares that evidence and does not issue audit reports or certifications; independent auditors and certification bodies do. Before signing, confirm with the provider which items are one-time, which recur, and what the retainer does and does not include.
