Contentful to Payload CMS: The Complete Migration Guide

Migrating from Contentful to Payload CMS means exporting your content as JSON using the contentful-export CLI, transforming each Rich Text document from Contentful's AST format into Payload's Lexical schema with a recursive TypeScript function, rebuilding your content model as Payload collections in code, and re-importing assets and entries via Payload's REST API or local SDK. This guide walks through every step with working TypeScript code, including the Rich Text → Lexical transformer that no other migration guide provides.

I've gone through this process for clients who were paying $1,500 to $4,000 per month for Contentful at scale. The bill wasn't the only reason — the locale pricing model, the API call overages, and the JSON link resolution overhead were all adding up. Payload, self-hosted on a $20 VPS with Cloudflare R2 for assets, handles the same workload for a fraction of the cost and with better developer ergonomics. This guide documents the full technical path.

---

The Contentful cost problem — and why it compounds

Contentful's pricing is often fine at the start. The problem is that the model is designed to scale your costs faster than your business scales.

The Team plan runs around $360 per month, but that base number is misleading. Contentful prices its record limit per locale. If you have a site in English, French, and German, your effective record capacity triples — but so does your cost if you breach the limit. A team that adds its second language typically sees the bill jump before they expect it.

The API call model compounds this further. The Contentful Delivery API is a network-hosted service, and every page load that fetches content counts against your monthly allowance. A traffic spike — a product launch, a viral article, a newsletter send — translates directly into a bill spike. Teams who have gone viral on Hacker News have reported Contentful overage charges exceeding their entire hosting cost for that month.

There is also the sys.id link resolution problem that never goes away. Contentful's API returns references as link objects — { sys: { type: 'Link', linkType: 'Entry', id: '...' } } — rather than resolved data. Fetching a page with multiple related entries requires multiple API calls or the include parameter with depth limits. Payload resolves relationships at query time via depth, returning fully-populated data in a single request.

The combination of locale pricing, API overages, and resolution overhead is what pushes growing teams toward self-hosted alternatives. Payload is the most mature TypeScript-native option available in 2026. If you want the architectural comparison first, see the Payload CMS vs Contentful comparison.

---

How Contentful structures data — and what that means for migration

Before writing a single line of migration code, it helps to have a clear mental model of how Contentful's data maps to Payload's. The concepts are similar but the terminology and schema are different enough to cause confusion.

The most technically significant mapping is Rich Text → Lexical. Contentful stores Rich Text as a JSON Abstract Syntax Tree (AST) with its own node schema. Payload's Lexical editor also stores rich text as JSON, but with a completely different node schema. There is no automatic converter and no maintained npm package that handles the transform. The function in Section 4 of this guide is the original code you need.

A Contentful Blog Post content type with a title text field, a body Rich Text field, and an author reference field maps to a Payload collection like this:

// File: src/collections/Posts.ts
import { CollectionConfig } from 'payload'

export const Posts: CollectionConfig = {
  slug: 'posts',
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'body',
      type: 'richText',
      // Lexical is the default in Payload 3.x
    },
    {
      name: 'author',
      type: 'relationship',
      relationTo: 'authors',
    },
  ],
}

Keep this mapping in front of you as you work through the migration. Every content type becomes a collection, every reference field becomes a relationship field, and every Rich Text field becomes a Lexical richText field.

---

Extracting your Contentful data

Contentful provides two extraction paths: the contentful-export CLI for a complete one-shot dump, and the contentful-management SDK for scripted or incremental pulls.

The contentful-export CLI

For most migrations, start with the CLI. It produces a single JSON file containing everything — content types, entries, assets, and locale definitions — which gives you a stable snapshot to work against.

Install and run it:

npm install -g @contentful/contentful-export

contentful-export \
  --space-id YOUR_SPACE_ID \
  --environment-id master \
  --management-token YOUR_MANAGEMENT_TOKEN \
  --export-dir ./contentful-export \
  --include-drafts false

The output file at ./contentful-export/contentful-export-TIMESTAMP.json contains four top-level arrays: contentTypes, entries, assets, and locales. The entries array is what you will spend most of your time transforming.

A typical entry looks like this:

{
  "sys": {
    "id": "4gSSbjCFEorYXqrgDIP2FA",
    "contentType": {
      "sys": { "id": "blogPost" }
    }
  },
  "fields": {
    "title": { "en-US": "My First Post" },
    "body": {
      "en-US": {
        "nodeType": "document",
        "content": [
          {
            "nodeType": "paragraph",
            "content": [
              {
                "nodeType": "text",
                "value": "Hello, world.",
                "marks": [],
                "data": {}
              }
            ],
            "data": {}
          }
        ],
        "data": {}
      }
    }
  }
}

Notice three things. First, every field is wrapped in a locale key ("en-US") even for single-locale sites. Second, the Rich Text body is a nested JSON tree with nodeType as the discriminant. Third, asset references anywhere in the document come through as { sys: { type: 'Link', linkType: 'Asset', id: '...' } } — the actual URL is in the assets array, not inline.

Using the contentful-management SDK for incremental pulls

If you need to pull content incrementally (e.g., for a live site migration where content keeps updating), the SDK gives you more control:

// File: scripts/contentful-pull.ts
import { createClient } from 'contentful-management'

const client = createClient({
  accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN!,
})

async function pullEntries(contentTypeId: string) {
  const space = await client.getSpace(process.env.CONTENTFUL_SPACE_ID!)
  const environment = await space.getEnvironment('master')

  let skip = 0
  const limit = 100
  const entries: any[] = []

  while (true) {
    const batch = await environment.getEntries({
      content_type: contentTypeId,
      limit,
      skip,
      order: 'sys.createdAt',
    })

    entries.push(...batch.items)

    if (skip + limit >= batch.total) break
    skip += limit
  }

  return entries
}

The pagination pattern here is important. Contentful's API caps responses at 1,000 entries per request, so for large datasets you need the skip-based loop shown above. For very large spaces (50k+ entries), consider using the Contentful Management API's sync endpoint instead, which is more efficient for large exports.

---

Transforming Contentful Rich Text to Payload Lexical

This is the hard part — and the part no other guide covers. Contentful Rich Text and Payload Lexical both store content as JSON trees, but their schemas are different enough that you cannot use either directly. You need a transformer.

Here is the Contentful node schema for a heading:

{
  "nodeType": "heading-1",
  "content": [
    {
      "nodeType": "text",
      "value": "My Heading",
      "marks": [{ "type": "bold" }],
      "data": {}
    }
  ],
  "data": {}
}

And the equivalent Payload Lexical node:

{
  "type": "heading",
  "tag": "h1",
  "children": [
    {
      "type": "text",
      "text": "My Heading",
      "format": 1
    }
  ]
}

The differences are: nodeType becomes type, content becomes children, headings flatten their level into a tag property, text value becomes text, and marks becomes a numeric format bitmask (1 = bold, 2 = italic, 3 = bold + italic).

The transformer below handles the common node types: paragraphs, headings, text with marks, hyperlinks, embedded asset blocks, and embedded entry inline nodes. It requires a pre-built asset ID map — a Map<string, string> from Contentful asset IDs to Payload media IDs — because the Lexical upload node references the Payload ID, not the Contentful one. You build this map during the asset migration step in Section 7.

// File: scripts/transform-rich-text.ts
import type { SerializedEditorState } from 'lexical'

// Contentful mark types map to Lexical format bitmask
const MARK_FLAGS: Record<string, number> = {
  bold: 1,
  italic: 2,
  underline: 8,
  code: 16,
}

function handleMarks(marks: Array<{ type: string }>): { format: number } {
  const format = marks.reduce((acc, mark) => {
    return acc | (MARK_FLAGS[mark.type] ?? 0)
  }, 0)
  return { format }
}

function transformNode(
  node: any,
  assetMap: Map<string, string>,
  entryMap: Map<string, string>,
): any {
  switch (node.nodeType) {
    case 'document':
      return {
        root: {
          type: 'root',
          children: node.content.map((child: any) =>
            transformNode(child, assetMap, entryMap),
          ),
          direction: 'ltr',
          format: '',
          indent: 0,
          version: 1,
        },
      }

    case 'paragraph':
      return {
        type: 'paragraph',
        children: node.content.map((child: any) =>
          transformNode(child, assetMap, entryMap),
        ),
        direction: 'ltr',
        format: '',
        indent: 0,
        version: 1,
      }

    case 'heading-1':
    case 'heading-2':
    case 'heading-3':
    case 'heading-4':
    case 'heading-5':
    case 'heading-6': {
      const tag = node.nodeType.replace('heading-', 'h') as
        | 'h1'
        | 'h2'
        | 'h3'
        | 'h4'
        | 'h5'
        | 'h6'
      return {
        type: 'heading',
        tag,
        children: node.content.map((child: any) =>
          transformNode(child, assetMap, entryMap),
        ),
        direction: 'ltr',
        format: '',
        indent: 0,
        version: 1,
      }
    }

    case 'text':
      return {
        type: 'text',
        text: node.value,
        ...handleMarks(node.marks ?? []),
        mode: 'normal',
        style: '',
        detail: 0,
        version: 1,
      }

    case 'hyperlink':
      return {
        type: 'link',
        url: node.data.uri,
        children: node.content.map((child: any) =>
          transformNode(child, assetMap, entryMap),
        ),
        direction: 'ltr',
        format: '',
        indent: 0,
        version: 1,
        fields: {
          linkType: 'custom',
          newTab: false,
          url: node.data.uri,
        },
      }

    case 'embedded-asset-block': {
      const contentfulAssetId = node.data.target.sys.id
      const payloadMediaId = assetMap.get(contentfulAssetId)

      if (!payloadMediaId) {
        console.warn(`Asset not found in map: ${contentfulAssetId}`)
        // Return an empty paragraph rather than breaking the document
        return {
          type: 'paragraph',
          children: [{ type: 'text', text: '', format: 0, version: 1, mode: 'normal', style: '', detail: 0 }],
          direction: 'ltr',
          format: '',
          indent: 0,
          version: 1,
        }
      }

      return {
        type: 'upload',
        relationTo: 'media',
        value: payloadMediaId,
        fields: {},
        format: '',
        version: 2,
      }
    }

    case 'embedded-entry-inline': {
      const contentfulEntryId = node.data.target.sys.id
      const payloadEntryId = entryMap.get(contentfulEntryId)

      // Render as a relationship reference node.
      // If your Lexical config includes a custom relationship node, map to that.
      // Otherwise, fall back to a link using the Payload document URL.
      return {
        type: 'relationship',
        relationTo: 'posts', // adjust to the correct collection slug
        value: payloadEntryId ?? contentfulEntryId,
        version: 1,
      }
    }

    case 'unordered-list':
      return {
        type: 'list',
        listType: 'bullet',
        children: node.content.map((child: any) =>
          transformNode(child, assetMap, entryMap),
        ),
        direction: 'ltr',
        format: '',
        indent: 0,
        version: 1,
        start: 1,
        tag: 'ul',
      }

    case 'ordered-list':
      return {
        type: 'list',
        listType: 'number',
        children: node.content.map((child: any) =>
          transformNode(child, assetMap, entryMap),
        ),
        direction: 'ltr',
        format: '',
        indent: 0,
        version: 1,
        start: 1,
        tag: 'ol',
      }

    case 'list-item':
      return {
        type: 'listitem',
        children: node.content.map((child: any) =>
          transformNode(child, assetMap, entryMap),
        ),
        direction: 'ltr',
        format: '',
        indent: 0,
        version: 1,
        value: 1,
        checked: undefined,
      }

    case 'hr':
      return {
        type: 'horizontalrule',
        version: 1,
      }

    default:
      console.warn(`Unhandled Contentful node type: ${node.nodeType}`)
      return {
        type: 'paragraph',
        children: [{ type: 'text', text: '', format: 0, version: 1, mode: 'normal', style: '', detail: 0 }],
        direction: 'ltr',
        format: '',
        indent: 0,
        version: 1,
      }
  }
}

export function transformRichText(
  contentfulDocument: any,
  assetMap: Map<string, string>,
  entryMap: Map<string, string>,
): SerializedEditorState {
  return transformNode(contentfulDocument, assetMap, entryMap) as SerializedEditorState
}

A few things worth explaining in this code. The handleMarks function converts Contentful's marks array into Lexical's numeric format bitmask using bitwise OR. Bold is 1, italic is 2, both together is 3 — Lexical checks these with bitwise AND internally. The embedded-asset-block handler has a defensive fallback that logs a warning and returns an empty paragraph if the asset ID is not in the map yet, rather than throwing and breaking the entire migration. The embedded-entry-inline handler returns a relationship node — if your Lexical config does not include a custom relationship node, replace this with a standard link node pointing to the entry's public URL.

The assetMap and entryMap parameters are both Map<string, string> objects mapping Contentful IDs to Payload IDs. You build them during the import steps in Sections 6 and 7.

---

Rebuilding the content model in Payload

With the transformation logic in place, the next step is rebuilding your Contentful content types as Payload collections. This is the most readable part of the migration — Payload's TypeScript-first config makes the schema self-documenting.

Here is a complete example for a typical content model: Blog Posts, Authors, and a Site Settings global.

// File: src/collections/Authors.ts
import { CollectionConfig } from 'payload'

export const Authors: CollectionConfig = {
  slug: 'authors',
  admin: {
    useAsTitle: 'name',
  },
  fields: [
    {
      name: 'name',
      type: 'text',
      required: true,
    },
    {
      name: 'bio',
      type: 'textarea',
    },
    {
      name: 'avatar',
      type: 'upload',
      relationTo: 'media',
    },
  ],
}

// File: src/collections/Posts.ts
import { CollectionConfig } from 'payload'
import { lexicalEditor } from '@payloadcms/richtext-lexical'

export const Posts: CollectionConfig = {
  slug: 'posts',
  admin: {
    useAsTitle: 'title',
  },
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'slug',
      type: 'text',
      required: true,
      unique: true,
      admin: {
        position: 'sidebar',
      },
    },
    {
      name: 'body',
      type: 'richText',
      editor: lexicalEditor({}),
    },
    {
      name: 'author',
      type: 'relationship',
      relationTo: 'authors',
    },
    {
      name: 'publishedAt',
      type: 'date',
      admin: {
        position: 'sidebar',
      },
    },
  ],
}

// File: src/globals/SiteSettings.ts
import { GlobalConfig } from 'payload'

export const SiteSettings: GlobalConfig = {
  slug: 'site-settings',
  fields: [
    {
      name: 'siteName',
      type: 'text',
    },
    {
      name: 'siteDescription',
      type: 'textarea',
    },
    {
      name: 'defaultOgImage',
      type: 'upload',
      relationTo: 'media',
    },
  ],
}

One pattern worth noting: fields that were Contentful "Symbol" (short text) map to Payload text, "Text" (long text) maps to textarea, "Integer" and "Number" both map to number, "Boolean" maps to checkbox, and "Date and time" maps to date. Contentful's "JSON Object" field has no direct Payload equivalent — use a json field type or model the structure as nested group or array fields depending on how your frontend consumes it.

If your Contentful space uses localization, enable it in Payload's config and add localized: true to each localizable field. The Payload CMS localization guide covers the full setup with next-intl.

---

Handling references and linked entries

References are the most common migration failure point. Teams import all their entries but end up with broken relationship fields because they didn't account for the ID change — a Contentful entry ID like 4gSSbjCFEorYXqrgDIP2FA becomes a MongoDB ObjectID or a PostgreSQL integer in Payload. Every relationship field needs to be remapped.

The solution is a two-pass import. In the first pass, you create all entries with their scalar fields only (title, text, dates) and record the mapping from old Contentful ID to new Payload ID. In the second pass, you update each entry with its relationship fields now that you have the Payload IDs.

// File: scripts/import-entries.ts
import { getPayload } from 'payload'
import config from '@/payload.config'

type IdMap = Map<string, string>

async function importPosts(
  entries: any[],
  authorMap: IdMap,
): Promise<IdMap> {
  const payload = await getPayload({ config })
  const postMap: IdMap = new Map()

  // Pass 1 — import scalar fields only
  for (const entry of entries) {
    const fields = entry.fields
    const locale = 'en-US' // adjust for your locale key

    const created = await payload.create({
      collection: 'posts',
      data: {
        title: fields.title?.[locale] ?? '',
        slug: fields.slug?.[locale] ?? '',
        publishedAt: fields.publishedAt?.[locale] ?? null,
        // Intentionally omit `author` and `body` for now
      },
    })

    postMap.set(entry.sys.id, created.id as string)
  }

  // Pass 2 — update with relationships and rich text
  for (const entry of entries) {
    const fields = entry.fields
    const locale = 'en-US'
    const payloadId = postMap.get(entry.sys.id)!

    const contentfulAuthorId = fields.author?.[locale]?.sys?.id
    const payloadAuthorId = contentfulAuthorId
      ? authorMap.get(contentfulAuthorId)
      : undefined

    // Rich text transform (assetMap and entryMap built during asset import)
    // Pass these in once asset migration is complete
    const body = fields.body?.[locale]
      ? transformRichText(fields.body[locale], assetMap, postMap)
      : undefined

    await payload.update({
      collection: 'posts',
      id: payloadId,
      data: {
        author: payloadAuthorId,
        body,
      },
    })
  }

  return postMap
}

The two-pass approach means you can run the script in order: import authors first (they have no references), get the authorMap, import posts with author relationships, get the postMap, and then use postMap as the entryMap in the rich text transformer for any embedded-entry-inline nodes.

For deeper reference chains — entries that reference entries that reference entries — you need to topologically sort your imports so dependencies are always imported before dependents. For most blog-style content models this isn't necessary, but for commerce or complex editorial models it is. The Payload CMS SDK CLI toolkit covers how to set up the authenticated client for running these kinds of scripts reliably in a TypeScript environment.

---

Asset migration — downloading and re-importing

Assets are straightforward in principle: download each file from the Contentful CDN and re-upload it to Payload's media collection. The result is the assetMap you need for the rich text transformer.

// File: scripts/import-assets.ts
import fs from 'fs'
import path from 'path'
import FormData from 'form-data'
import fetch from 'node-fetch'
import { getPayload } from 'payload'
import config from '@/payload.config'

type IdMap = Map<string, string>

export async function importAssets(
  contentfulAssets: any[],
): Promise<IdMap> {
  const payload = await getPayload({ config })
  const assetMap: IdMap = new Map()

  for (const asset of contentfulAssets) {
    const locale = 'en-US'
    const file = asset.fields?.file?.[locale]

    if (!file?.url) {
      console.warn(`Skipping asset with no file URL: ${asset.sys.id}`)
      continue
    }

    const url = `https:${file.url}`
    const filename = path.basename(file.url.split('?')[0])
    const contentType = file.contentType ?? 'application/octet-stream'

    try {
      // Download the file from Contentful CDN
      const response = await fetch(url)
      if (!response.ok) {
        throw new Error(`Failed to download asset: ${response.status}`)
      }
      const buffer = await response.buffer()

      // Write to a temp file (Payload local upload expects a file path or buffer)
      const tempPath = path.join('/tmp', filename)
      fs.writeFileSync(tempPath, buffer)

      // Upload to Payload media collection
      const formData = new FormData()
      formData.append('file', fs.createReadStream(tempPath), {
        filename,
        contentType,
      })

      // Use Payload REST API endpoint for uploads
      const uploadResponse = await fetch(
        `${process.env.PAYLOAD_PUBLIC_SERVER_URL}/api/media`,
        {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env.PAYLOAD_API_KEY}`,
            ...formData.getHeaders(),
          },
          body: formData,
        },
      )

      if (!uploadResponse.ok) {
        const error = await uploadResponse.text()
        throw new Error(`Payload upload failed: ${error}`)
      }

      const uploaded = (await uploadResponse.json()) as { doc: { id: string } }
      assetMap.set(asset.sys.id, uploaded.doc.id)

      // Clean up temp file
      fs.unlinkSync(tempPath)

      console.log(`Imported: ${filename} → ${uploaded.doc.id}`)
    } catch (err) {
      console.error(`Error importing asset ${asset.sys.id}:`, err)
      // Continue with remaining assets rather than aborting
    }
  }

  return assetMap
}

Run asset migration before entry migration. The assetMap returned here is what you pass into transformRichText to resolve embedded-asset-block nodes into Payload upload nodes with the correct Payload media ID.

A few practical notes. The Contentful CDN URL comes through without a protocol prefix (//images.ctfassets.net/...), so the https: prepend is necessary. Large asset libraries (thousands of images) should add a concurrency limit — p-limit at 5–10 concurrent downloads prevents rate limiting from the Contentful CDN. If you are migrating to Payload with S3 or Cloudflare R2 storage, the REST upload will work the same way since Payload handles the storage adapter internally.

---

Cost savings calculation

Here is the math for a common migration scenario so you can apply it to your own numbers.

Hypothetical: Series B SaaS, content-heavy marketing site

Annual difference: roughly $8,500 saved per year on this profile, before accounting for any Enterprise-tier costs.

The engineering effort to migrate is typically 20–40 hours for a developer comfortable with TypeScript and Node.js scripting, using the code in this guide. At a $150/hour blended rate that is $3,000–$6,000 of one-time cost, which breaks even inside the first year.

The savings scale with complexity. Sites with more locales, higher API call volumes, or Contentful Enterprise contracts see proportionally larger savings. The self-hosted Payload model does not penalise you for adding locales, publishing more content, or receiving more traffic. The cost curve is flat.

To calculate your own estimate: take your current Contentful bill, subtract the Contentful-specific line items, and add a VPS ($20–40/month depending on load), a managed Postgres instance ($0–25/month depending on size), and R2 or S3 storage at actual storage cost.

For teams weighing vendor lock-in risk as a factor alongside cost, the CMS vendor lock-in: Sanity vs Payload comparison covers portability in more depth.

---

FAQ

Does this migration work for Contentful spaces with multiple locales?

Yes, but with additional complexity. The contentful-export output includes locale keys on every field. You need to either run the migration per locale (exporting and importing one locale at a time) or modify the import script to call payload.create with a locale parameter for each locale in your Contentful space. Enable localization in your Payload config first and add localized: true to each field that should carry locale data.

What happens to Contentful Rich Text nodes my transformer doesn't handle?

The default case in the transformNode function logs a warning and returns an empty paragraph. This keeps the document valid but drops the content. Before running at scale, do a dry run on your export JSON and grep the logs for "Unhandled Contentful node type" to see if your content uses any node types not covered — blockquote and table are the most common gaps for editorial content models.

Can I run the migration without downtime?

A zero-downtime migration requires keeping Contentful live while importing, then doing a final delta sync before cutover. The contentful-management SDK supports a sync token approach that pulls only content changed since your last export. The recommended approach is: run the full initial import, set up a webhook from Contentful that writes changes to Payload in real time, then cut DNS over to Payload when you are confident the content is in sync. The Payload CMS n8n integration patterns covers webhook-to-Payload pipelines if you want to automate the delta sync step.

Do I need to update my frontend after migrating?

Yes, but typically the changes are smaller than expected. Your data fetching layer shifts from Contentful SDK calls to Payload REST or local API calls. The field names stay the same if you keep them consistent during collection definition. The biggest frontend change is the Rich Text renderer — you replace documentToReactComponents from @contentful/rich-text-react-renderer with Payload's Lexical React renderer. See the Payload Lexical documentation for the renderer setup.

What about Contentful webhooks and preview URLs?

Contentful's webhook system uses a Contentful-specific signing mechanism. After migration, replace any Contentful webhook endpoints with Payload's built-in hooks system (afterChange, afterCreate in collection hooks) or with n8n/Zapier workflows triggered by Payload webhooks. Preview URLs using the Contentful Preview API need to be rebuilt against Payload's draft/preview system, which uses Next.js draft mode.

---

Migrate without doing it yourself

The migration guide above is the complete technical path. Every section has working TypeScript code you can adapt directly.

If your team has years of Contentful content, a complex content model with many reference types, or production traffic that makes a risky cutover unacceptable, the engineering hours add up quickly. The Payload CMS migration service covers the full migration: content model rebuild, Rich Text transformation, asset pipeline, frontend adapter updates, and zero-downtime cutover planning.

---

If you have questions about specific Contentful node types your transformer isn't handling, or you are working through a particularly complex reference structure, leave a comment below. And subscribe if you want more practical Payload CMS implementation guides as they come out.

Thanks, Matija