Migrate from Contentstack to Payload

Migrate from Contentstack to Payload: what moves and what needs rebuilding

If your Contentstack renewal, plan change or data residency requirement is pushing you to host content yourself, the move to Payload is a schema translation plus a scripted import, and, if Payload runs inside your Next.js app, a frontend switch. Content types become code-defined collections and blocks in TypeScript, entries and assets are written into them by scripts, and the delivery layer is rewired to query Payload instead of the Contentstack Content Delivery API. Most of the work sits in the schema and the import scripts, so that is where you should spend review time.

Internal developers usually own this work, with an implementation partner helping on the schema design, import tooling and cutover plan. Effort and risk depend mainly on how many content types, global fields and modular blocks you have, how many locales are live, how much custom workflow and role logic sits in Contentstack, and whether your frontend is already Next.js. Payload is MIT licensed, installs directly into a Next.js /app folder and supports MongoDB, PostgreSQL and SQLite, so the database choice is a decision you make early. Confirm the exact database engine and hosting target with your team before estimating anything, because the import script and backup routine differ between them.

Two things to check before you start. First, Contentstack's CLI export does not carry every part of a stack into a file you can reuse as-is, so inventory what lives only in the Contentstack UI (workflows, roles, scheduled publishing, webhooks) and decide whether each one is rebuilt, dropped or replaced. Second, confirm current Payload release details and any breaking changes against the Payload GitHub repository and its releases before you pin a version, since the v4.0.0 line is still in beta. Ask your implementation partner for the schema map, import script plan and cutover checklist in writing before work starts.

Which Contentstack features map to Payload and which need rework

This table maps common Contentstack capabilities to their closest Payload equivalents and marks each row as clean, needs rework or gap. Read the status column first, then confirm how your own stack uses content types, workflows and roles before you plan the import. Most content models carry over cleanly, while workflow stages, user accounts and any Contentstack-specific delivery behavior need deliberate rebuilding.

Contentstack capability	Payload equivalent	Status
Content types	Collections defined in TypeScript config	Clean
Global fields and reusable schemas	Reusable field sets and globals, with blocks for repeated layouts	Needs rework
Modular blocks	Block-based layout builder fields	Needs rework
References between entries	Relationship and upload fields, resolved by ID during import	Needs rework
Rich text fields	Lexical rich text editor, so stored markup must be converted	Needs rework
Localization and locales	Built-in localization per field and collection	Clean
Versions and drafts	Versions and drafts, but historical Contentstack versions are not carried over	Needs rework
Workflow stages and approvals	No direct equivalent; rebuild with hooks, access control or custom fields after you confirm how your stack uses them	Gap
Roles and user permissions	Field-level access control and built-in authentication for admin and customer users; existing Contentstack user accounts are not carried over by a supplied export path	Gap
Webhooks	Document and field hooks plus outbound calls in your own code, with rebuilt triggers	Needs rework
Asset management	Upload collections with files stored in your chosen storage	Needs rework
Delivery APIs	Payload's REST and GraphQL endpoints inside your Next.js app, so frontend queries change	Needs rework
Editorial preview	Live preview and a customizable React admin panel	Clean

Data, assets and integrations to move or rebuild

Contentstack content, files, people and connected services do not move the same way. Entries and the content model give you the most to start from, while users, roles and integrations usually need to be rebuilt in Payload. Confirm exactly what the Contentstack CLI includes before you write any import script.

Entries and the content model

The export gives you content types, global fields and entries as JSON, which you map to Payload collections, globals and blocks in a TypeScript config. Your import scripts then call Payload's Local API to create entries, keeping references between documents intact. Plan a field-by-field mapping first, and check how modular blocks and references appear in the export. Confirm with Contentstack's export documentation which modules, entry versions and branches the CLI includes, since only the latest versions may come through.

Asset files and metadata

Asset files usually need to be downloaded separately from their metadata, so check whether the export includes binaries or only references. Your script uploads each file into a Payload upload collection and then rewrites entry references to the new asset IDs. Titles, descriptions, locales and file names need a collision check, because two assets with the same name can overwrite each other. Storage location is your decision, so plan where the files live before the first import run.

Users and roles

Treat users and roles as a rebuild, not a copy. Confirm whether the export includes user accounts and roles at all, since many export setups leave them out. In Payload, admin and customer users are created through its built-in authentication, and access control is written as code on each collection and field. Map each Contentstack role to explicit permissions, and re-invite editors through a controlled process rather than migrating password data.

Webhooks, search and preview

Webhooks, search indexes, live preview endpoints and third-party services are configured outside the content itself, so they seldom come across in an export. Inventory every webhook that fires on publish, every search index fed from Contentstack and every preview URL your frontend uses. In Payload, you rebuild these with hooks, a search provider of your choice and the live preview feature inside the Next.js app. Test each one against staging content before you switch the frontend.

How Contentstack content models translate to Payload collections and blocks

In Payload, the content model is not a setting in a web console. Collections, fields and blocks are defined in TypeScript code that lives in your repository, so every change to a content type becomes a reviewed commit with a history. Contentstack content types and their global fields have to be re-expressed as Payload collections, globals and field definitions. Before any import script is written, create a mapping document for each Contentstack content type. For each one, list its fields, the Payload field type that will hold each value, whether the field is required, which locales apply, and which entries it references. This document becomes the contract that your import code and your frontend both follow.

Contentstack modular blocks map to a blocks field, which Payload supports through its block-based layout builder. Each block type in Contentstack becomes one block definition with its own fields, and the order of blocks on a page is stored as an array. Check each modular block for nested blocks or global field reuse, because those need a decision: either define a shared block config and reference it, or copy the fields into each collection. References become relationship fields that point to another collection, so confirm for every reference field which collection it targets and whether it allows one or many values. Locales become Payload localization, which is set in the Payload config and applied per field. Confirm which fields are localized in Contentstack and which are shared across locales, because a mismatch here causes wrong content to appear in the wrong language.

Because Payload generates TypeScript types automatically from its collection and field definitions, the frontend can be typed against the same schema the CMS uses. When a field is renamed or a block changes shape, the compiler flags every place in the Next.js code that still expects the old shape, which is the main practical benefit of a code-defined model. The mapping document should record the generated type name for each collection and block so the frontend team can check it during the build. Keep the mapping in version control next to the Payload config, and review it with the content owners before import begins, since any field you miss in the mapping will be missing from the migrated content.

Sequencing a Contentstack to Payload migration

The sequence moves Contentstack content into Payload in controlled stages, so each stage produces a checked artifact before the next one starts. Editors keep working in Contentstack until the parity checks pass, and the final export is archived before anything is deleted.

Inventory the stack before writing any code
Your content lead and a developer list every content type, global field, entry count, asset library, locale, environment, workflow, role, webhook and integration in the Contentstack stack. Record which content types feed which frontend routes and which integrations depend on the delivery API. The output is an inventory register with an owner for each item. You know the step is done when the register has been reviewed by the editors and the engineers, and every unresolved question has a named owner. Roles and permissions do not come across in a content export, so list them by hand here and note which ones need to be recreated as Payload access control rules.
Map the schema into Payload collections and blocks
Translate each Contentstack content type into a Payload collection in TypeScript, and each modular block or global field into a Payload block or global. Document how references, localized fields and taxonomy relationships will be expressed, and which fields Payload's generated types will cover. The output is a mapping document that lists source field, target field, type conversion and any content that must be reshaped. Ask your Payload developers to confirm the database choice (MongoDB, PostgreSQL or SQLite) at this stage, because it shapes the import tooling.
Pilot one content type with a repeatable import script
Build a single content type in a staging Payload install inside the Next.js app, then write an import script that reads the Contentstack export, creates entries, uploads assets and links references. Run it several times against a fresh staging database to prove it is repeatable and idempotent. Compare a sample of imported entries with their source, field by field, including rich text, locales and asset links. The output is a working import script, a run log and a parity checklist for the pilot type. Only move on when two consecutive clean runs produce identical results.
Run both systems in parallel with editor review
Migrate the remaining content types with the same script, then serve the new Payload-backed frontend on a staging or preview URL while Contentstack remains the source for editors. Editors and content owners review rendered pages against the live Contentstack output, and publishing changes made in one system are reconciled with the other by a named process, not by hand. The output is a completed parity checklist covering routes, metadata, media, redirects and locales, with every mismatch logged and closed. Ask your team to decide, before this step starts, how long the parallel period runs and who signs off on it.
Cut over the frontend and the editorial workflow
Switch production traffic to the Payload-backed frontend, move editors to the Payload admin panel, and recreate the approval steps that Contentstack workflows enforced using Payload versions, drafts and access control. Update webhooks, search indexing and any downstream integration that called the Contentstack delivery API. The output is a cutover runbook with a rollback path and a record of who approved the switch. The step is done when editors have published through the new workflow and the monitoring shows no broken routes or missing assets.
Archive the final export and decommission Contentstack
After the cutover has been stable for a period your organization sets, run a final export from Contentstack, including assets, and store it in an access-controlled archive that your records policy allows. Check that the archive opens, that entry counts and asset checksums match the source, and that the roles and users you recorded in step one are documented outside the export. Only then cancel the subscription or delete the stack. The output is a signed archive of the final export and a decommissioning record. Confirm your retention obligations with your legal and compliance teams before deletion.

What drives the cost and duration of the move

This table lists the factors that most change the effort of moving Contentstack content into Payload collections and blocks, with a note on how to reduce each one. Read it before requesting a quote, because the same stack can take very different effort depending on its model shape, locales and frontend. Scope these drivers in writing with any implementation partner so the estimate reflects your actual content.

Driver	Why it matters	How to keep it down
Content types and blocks	Each Contentstack content type becomes a Payload collection or global, and each modular block becomes a block definition. More types mean more TypeScript config, more import mappings and more test cases.	Audit unused content types before export. Merge near-duplicate types into one collection with a block field where the content shape allows it.
References and their depth	Reference fields must be imported in dependency order and remapped to Payload relationship IDs. Deeply nested references, or references inside blocks, need multi-pass imports and extra validation.	Map the reference graph first. Flatten nesting where editors can accept it, and import leaf collections before the entries that point to them.
Locales and fallbacks	Each locale multiplies entries to import and must map to Payload localization settings, including fallback rules. Missing translations can surface as blank pages in production.	List active locales and confirm which fields are localized. Drop locales with little traffic or content from the first migration wave.
Asset volume and filename collisions	Assets must be downloaded, re-uploaded to the Payload upload collection and relinked. Duplicate filenames across folders or stacks cause overwrites or broken links.	Deduplicate assets by checksum, rename colliding files during export and keep a mapping table from old asset IDs to new media records.
Workflows and roles	Contentstack roles, workflow stages and approvals are not carried over as data. Payload access control and drafts must be designed and rebuilt in code.	Document the current approval paths and reduce them to the states editors actually use. Decide access rules before importing content.
Integrations to rebuild	Webhooks, search indexes, preview endpoints and third-party connectors that read from Contentstack must be re-pointed to Payload APIs and hooks.	Inventory every consumer of the Contentstack delivery API. Retire integrations no team still uses before rebuilding them.
Frontend already on Next.js	Payload installs into an existing Next.js /app folder, so a Next.js frontend shortens the frontend switch. A non-Next.js frontend needs a rebuild of the rendering layer on top of the Payload API.	Confirm the framework and version of the current frontend. If it is not Next.js, scope the rendering rebuild as a separate workstream.
Editors to train	Each editor group needs training on the new admin panel, drafts, live preview and block layouts. Training scales with the number of roles and the number of editing workflows.	Train a small group of power users who then support colleagues. Use screenshots from the Payload admin built for your own collections.
Cost components and timing	Internal engineering time, implementation partner fees, Payload hosting and database, and ongoing maintenance each carry different costs. Hosting, database and maintenance recur, while data mapping, migration scripts and training are one-time.	Ask for a quote that separates one-time migration work from recurring hosting, backups, upgrades and support. Request a written scope before work starts.

How the move differs by starting point

When one brand runs on one Contentstack stack and the frontend is already Next.js, the migration is mostly a schema translation and a data import. Payload installs into the Next.js /app folder, so the content model, the admin panel and the delivery code can live in one repository. The main decision is whether the new CMS replaces the frontend's data layer in one cutover or runs alongside the old API for a short period.

Schema work: Each Contentstack content type maps to a Payload collection, and shared global fields become reusable field definitions. Expect the work to be mostly mechanical, with a review pass on rich text and modular blocks.
Import script: A single script can read the exported JSON, write entries in dependency order and attach assets. Test it against a copy of the content before it touches the target database.
Frontend switch: Components that call the Contentstack Delivery API need new data functions that query Payload's local API or REST endpoints. Routing and rendering usually stay the same.
Preview and drafts: Confirm that Payload's live preview and draft workflow cover the editorial habits your team uses today.
Decide first: Whether the Contentstack workflows and roles are rebuilt in full or simplified during the move, since the CLI export does not carry roles or permissions.

Before you start, confirm the exact export scope for your stack with the Contentstack documentation and your own environment.

What usually goes wrong and how to prevent it

Most Contentstack to Payload migrations fail in the handoff rather than in the export itself. The risks below share one root cause: content moves between two systems with different models for references, locales, drafts and secrets, and nothing checks the result until editors and readers see it.

References break on import order

Entries that link to other entries, assets or blocks only resolve if their targets already exist in Payload. Import in dependency order: assets first, then leaf collections such as authors or categories, then pages and entries that reference them. Store a map from each Contentstack entry UID to its new Payload ID, and write that map to a file so later runs can resolve references. Check that every relationship field is populated after each run, not only that the import finished without errors.

Asset collisions and lost metadata

Contentstack asset filenames are not guaranteed unique across folders, so two files named hero.jpg can overwrite each other on upload. Compute a checksum for each downloaded file, use it as the stored key, and keep the original title, description, tags and locale-specific alt text in the upload record. Re-running the script should skip files whose checksum already exists. Sample a set of assets in both systems and compare dimensions, byte size and metadata before you retire the source.

Locale fallbacks behave differently

Contentstack and Payload each define what a missing translation falls back to, and the defaults may not match your content. A field left empty in a secondary locale can show blank text in Payload while Contentstack displayed the master locale value. Write down the fallback rule each system applies for every content type, then configure Payload's localization to match. Verify with a checklist of pages in each non-default locale, including slugs and SEO fields.

Drafts and scheduled changes lost

A CLI export captures published content and the latest entry state, so unpublished drafts, pending workflow stages and scheduled publishes may not arrive in Payload. Ask editors to list in-flight work before the cutover, record which entries are scheduled, and recreate them as Payload drafts with versions enabled. Confirm with the vendor and your own export which draft and workflow data the export includes in your stack.

Stale content during the parallel run

While both systems run, the frontend may read Contentstack in some routes and Payload in others, and editors may keep working in the old system. Choose one source of truth per content type and a single cutover date for writes. Use a parity checklist that compares sampled pages from each system, and route the Next.js app through a flag so you can switch back quickly if readers see outdated content.

Secrets left in migration scripts

Migration scripts often hold Contentstack management tokens, delivery tokens and database connection strings written directly into the code or shell history. Load every credential from environment variables or your secrets manager, keep the scripts in a private repository, and rotate the Contentstack tokens once the export is complete. Review the commit history before you share the repository with the wider team.

Planning the frontend switch when Payload runs inside Next.js

Decide early whether Payload will share a Next.js application with your public site, because that choice sets how the frontend moves off Contentstack. Payload installs directly into an existing Next.js /app folder, so the admin panel, the API and the public pages can live in one codebase and one deployment. For a site that currently calls Contentstack's delivery API from a separate frontend, this means rewriting data fetching rather than only changing an endpoint. Pages that fetched entries over HTTP will instead read from Payload through its Local API inside server components, or through its REST or GraphQL endpoints when the consumer sits outside the app. Map each Contentstack delivery call in your current frontend to one of these access paths before you write code, and note which calls need the same query filters, locale parameters and reference depth.

Live preview needs its own configuration step. In Payload, you define a preview URL per collection or global, and the admin panel loads your frontend in an iframe with draft content. Your frontend must then read drafts when a preview request arrives and show published content otherwise. Test this with an editor account that has no delete rights, because preview exposes unpublished content to anyone who can open the admin panel. Confirm the Payload version you plan to use against the Payload releases page before you start. The researched releases include v3.91.0, released on October 15, 2026, and a v4.0.0 beta line still in progress, so pin an exact stable version in your lockfile and treat any beta as a separate evaluation.

Choose the deployment target before the frontend work starts, because it affects database, media storage and caching. Payload can deploy to Vercel, to Cloudflare Workers with R2 and D1, or be self-hosted anywhere, and the database choice (MongoDB, PostgreSQL or SQLite) is independent of that target. Ask your hosting team to confirm which combination meets your residency and uptime requirements, and plan a parallel run where the old Contentstack-fed site and the new Payload-fed site serve the same content until the cutover checks pass.

Questions buyers ask before a Contentstack to Payload migration

How much effort and cost does a Contentstack to Payload move involve?

The cost is mostly labor, and the labor depends on how much schema and content sits in your Contentstack stack. Payload itself is MIT licensed, so there is no license fee for the CMS code, but you still pay for hosting, a database (MongoDB, PostgreSQL or SQLite, per the Payload README), a CDN if you use one, and the people who write the export scripts, rebuild content types as TypeScript collections and blocks, and test the result. Costs that recur are hosting, database operations, monitoring and developer time for upgrades. One-time costs are the export, schema translation, import scripts, frontend work and testing. Ask any provider for a quote that separates these lines, lists the number of content types, modular blocks, locales and asset files in scope, and states what is excluded, such as frontend redesign or editorial training.

How long does a Contentstack to Payload migration take?

Duration varies with the size and complexity of the stack, not with the Payload code itself. A stack with a few content types and one locale is far quicker to move than one with many modular blocks, cross-referenced entries, several environments and a large asset library. The schedule also depends on how fast your team can answer questions about content meaning, and on how many rounds of editor testing the content model needs. No duration figure is supplied for this move, so ask for a timeline in the written scope, with milestones for schema translation, the first full import, editorial review and cutover. Treat any single number without a scope behind it with caution.

What does the client team need to provide during the migration?

The work needs three groups from your side. Content owners must confirm which entries are current, which are obsolete and how references between entries should behave after import. Developers must provide access to the Contentstack stack, hosting accounts, the Next.js codebase that will host Payload, and a decision on the database. Editors must test the imported content in the new admin panel, check previews, and sign off on workflows that replace Contentstack's. Plan for editor time in short, repeated sessions rather than one review at the end. Confirm these responsibilities in writing before work begins so that testing is not left to chance.

Can our own team migrate from Contentstack to Payload without outside help?

Yes, a capable in-house team can do the work, provided it has TypeScript and Next.js skills and time to write and run import scripts. Payload generates TypeScript types from code-defined collections and fields, which helps developers keep the schema and frontend aligned. The harder parts are usually mapping modular blocks and references, handling asset name collisions, and verifying that every locale and draft state arrived intact. If your team lacks that bandwidth, you can scope the migration as a fixed-scope engagement with DeployOpen, which plans, implements and documents the work inside your own infrastructure, with ongoing support available as a retainer.

What happens to users, roles and workflows during the move?

Contentstack's user records, roles and workflows do not transfer as a set of settings, so you must rebuild them. Payload includes built-in authentication, so admin and customer users live in the CMS itself, and access control is defined at the field level in code. Your team should write down every existing role, who holds it, and which approval steps each workflow requires, then recreate those in Payload collections and access rules. Test each role with real accounts before cutover. Also plan how you will invite editors and set passwords, since those credentials are not migrated.

Can Payload run in our own cloud account or in a region we choose?

Yes, according to the Payload README, Payload can deploy to Vercel, to Cloudflare Workers with R2 and D1, or be self-hosted anywhere. Self-hosting is the option that keeps content and editor data in the cloud account and region you select, which matters for residency rules. Confirm that your chosen database, storage and CDN support the region and retention you need. For licensing terms and the current deployment guidance, read the Payload GitHub repository. DeployOpen can implement and harden the deployment in your own accounts, but the cloud and region decisions remain yours.

Which Payload version should we target for a new build?

Target a released version that your team has tested, and check the release history before you start. The latest published release supplied for this topic is v3.91.0, released on October 15, 2026. A v4.0.0 beta line is also in progress, with v4.0.0-beta.2 published on October 16, 2026, so a beta should not be used for production content without a deliberate upgrade plan. Review the Payload GitHub releases page on the day you freeze the build, and schedule upgrades as part of ongoing operations.

How DeployOpen scopes, runs and supports the migration

DeployOpen plans, implements, integrates, documents and supports self-hosted open-source platforms inside your own infrastructure. For a move from Contentstack to Payload, we work from a written scope that covers the content model, the data import, the frontend switch and the hand-over to your team.

How we scope

Inventory of Contentstack content types, global fields, locales, environments and assets before any work starts
Written mapping of each content type to a Payload collection, global or block, with agreed exceptions
Agreed list of workflows, roles and integrations to rebuild or retire, documented in the fixed scope
Confirmed Payload deployment target, database (MongoDB, PostgreSQL or SQLite) and hosting region

How we build

Payload collections and blocks written in TypeScript, generated from the agreed content model
Import scripts that load exported entries and assets, with reference and block relationships checked after each run
Test imports on a copy of the export, with reconciliation reports comparing record counts and asset links
Frontend switch in the Next.js app, with preview, access control and localization tested before cutover

How we hand over

Documentation of the schema, import scripts, environment configuration and known gaps against the source stack
Runbook covering backups, Payload upgrades and the steps for adding a new collection or block
Knowledge transfer sessions for your developers and editors, recorded where your policies allow
Written record of the decisions made during mapping, so future changes have a clear reference

How we support

Post-launch fixes and questions covered by a retainer, scoped separately from the migration
Upgrade planning for Payload releases, including testing against your content model before rollout
Security testing of the new CMS and its APIs available as a separate engagement
Ask for the retainer terms, response expectations and upgrade scope in writing before signing

Migrate from Contentstack to Payload