Import Content into Payload CMS from a JSON File

Looking to import content into Payload CMS from a JSON file? Whether you're migrating data, setting up dynamic landing pages, or managing bulk content uploads, Payload CMS offers the flexibility to programmatically handle JSON data.

In this blog post, you'll learn how to import JSON content into Payload CMS using its powerful Node.js API. This is especially useful if you're managing a large collection of pages, blog posts, or products and want to automate the process.

Why Use JSON to Import Content in Payload CMS?

✅ Fast and Scalable Bulk Uploads
JSON allows you to upload hundreds of records into Payload CMS collections quickly and consistently.

✅ Easier Content Migration
If you're moving content from platforms like WordPress, Contentful, or Strapi, exporting to JSON and importing into Payload makes the process smoother.

✅ Ideal for Dynamic Blocks
JSON works great with Payload's blocks-based layout, letting you import complex nested fields/blocks like hero, features, or imageGrids without manual work.

Prerequisites

• Before you get started, make sure you have the following:
• A Payload CMS project set up locally or on your server
• Admin access to manage your collections
• A valid JSON file structured to match your Payload schema
• Node.js environment (for scripting the import)
  
  

Step-by-Step Guide to Import JSON into Payload CMS

We can import content either from a separate Node.js project or from within the Payload CMS project itself.

In this example, I’m importing the content from within the Payload project. This is often more straightforward because any import method requires access to the Payload config, collections, and database connection — all of which are already available when working inside the project.

This also makes it easier to use payload.run or make direct API calls using Payload’s local API.

1. Prepare Your JSON File

Make sure your JSON file matches the schema of your collection. For example, if you're importing into a landing-pages collection (landingpages.json):

[
  {
    "title": "Welcome to Buggerspot",
    "slug": "welcome",
    "layout": [
      {
        "blockType": "hero",
        "heading": "Build Better Websites with Buggerspot",
        "subheading": "Reliable web development services tailored to your needs."
      },
      {
        "blockType": "imageGrid",
        "items": [
          {
            "image": mediaId,  // Replace with actual media ID or external URL
            "caption": "Custom Design Work"
          },
          {
            "image": "mediaId",
            "caption": "SEO Optimized Layouts"
          }
        ]
      }
    ]
  },
  {
    "title": "Why Choose Buggerspot",
    "slug": "why-choose-us",
    "layout": [
      {
        "blockType": "hero",
        "heading": "Your Partner in Web Innovation",
        "subheading": "From static sites to full-scale CMS setups, we handle it all."
      },
      {
        "blockType": "imageGrid",
        "items": [
          {
            "image": mediaId,
            "caption": "Modern Stack (Next.js, Payload CMS)"
          },
          {
            "image": mediaId,
            "caption": "Flexible CMS Integrations"
          }
        ]
      }
    ]
  }
]

2. Create an Import Script

Use Payload’s local API to import data programmatically. Here’s a basic script (content-import.ts):

import { getPayload } from "payload";
import config from "./payload.config";
import { readFileSync } from "fs";
import path from "path";

const run = async () => {
  const payload = await getPayload({
    config,
  });

  const jsonPath = path.resolve("landingpages.json");
  const raw = readFileSync(jsonPath, "utf-8");
  const pages = JSON.parse(raw);

  for (const page of pages) {
    try {
      const res = await payload.create({
        collection: "landing-pages",
        data: page,
      });
      console.log("✅ Imported:", res.slug || res.id || res.title);
    } catch (err) {
      console.error("❌ Failed to import page:", page.title || page.slug, err);
    }
  }

  console.log("✅ All pages processed.");
};

run().catch((err) => {
  console.error("❌ Script error:", err);
});

3. Run the Script

If you're using TypeScript, you can run:

ts-node importPages.ts

Or you can use the payload run CLI command like this:

// In package.json
"scripts": {
  "content-import": "payload run content-import.ts"
}

bun run content-import
(or)
npm run content-import

The payload run command is designed to run custom scripts in the Payload environment, which automatically loads your config, connects to the database, and gives you access to Payload internals — no need to call getPayload() yourself.

Best Practices

✅ Validate JSON before importing (e.g., using JSONLint)
✅ Backup your database before large imports
✅ Use update instead of create if the content already exists
✅ Handle media uploads separately if your images are not externally hosted

If you are looking to update blocks in the collection using API, here is the blog.

Thank You!