Next
Import Export Plugin
This plugin adds features that give admin users the ability to download or create export data as an upload collection and import it back into a project.
Core Features
- Export data as CSV or JSON format via the admin UI
- Download the export directly through the browser
- Create a file upload of the export data
- Use the jobs queue for large exports
- Import collection data
- Preview data before exporting or importing
Installation
Install the plugin using any JavaScript package manager like pnpm, npm, or Yarn:
1
pnpm add @payloadcms/plugin-import-export
Basic Usage
In the plugins array of your Payload Config, call the plugin with options:
1
import { buildConfig } from 'payload'
2
import { importExportPlugin } from '@payloadcms/plugin-import-export'
3
4
const config = buildConfig({
5
collections: [Users, Pages],
6
plugins: [
7
importExportPlugin({
8
collections: [{ slug: 'users' }, { slug: 'pages' }],
9
// see below for a list of available options
10
}),
11
],
12
})
13
14
export default config
Jobs Queue Requirements
By default, the plugin uses Payload's Jobs Queue for import and export operations. Queued jobs require a runner to be configured, otherwise imports and exports will stay in "pending" status and never complete.
Configure jobs.autoRun in your Payload config so that queued jobs are processed:
1
import { buildConfig } from 'payload'
2
import { importExportPlugin } from '@payloadcms/plugin-import-export'
3
4
const config = buildConfig({
5
collections: [Users, Pages],
6
jobs: {
7
autoRun: [
8
{
9
cron: '*/5 * * * *', // Check every 5 minutes
10
queue: 'default',
11
},
12
],
13
},
14
plugins: [
15
importExportPlugin({
16
collections: [{ slug: 'users' }, { slug: 'pages' }],
17
}),
18
],
19
})
20
21
export default config
Alternatively, use allQueues: true to process jobs from all queues:
1
jobs: {
2
autoRun: [
3
{
4
allQueues: true,
5
cron: '*/5 * * * *',
6
},
7
],
8
},
For smaller datasets or testing, you can run imports and exports synchronously by setting disableJobsQueue: true in the per-collection ExportConfig or ImportConfig. This avoids the need for a jobs runner but blocks the request until the operation completes.
Options
Property | Type | Description |
|---|---|---|
| array | Collections to include Import/Export controls in. Array of collection configs with per-collection options. Defaults to all. |
| boolean | If true, enables debug logging. |
| `number \ | function` | Global maximum documents for export operations. Set to |
| `number \ | function` | Global maximum documents for import operations. Set to |
| function | Function to override the default export collection. Receives |
| function | Function to override the default import collection. Receives |
Per-Collection Configuration
Each item in the collections array can have the following properties:
Property | Type | Description |
|---|---|---|
| string | The collection slug to configure. |
| boolean \ | ExportConfig | Set to |
| boolean \ | ImportConfig | Set to |
ExportConfig Options
Property | Type | Description |
|---|---|---|
| number | Documents per batch during export. Default: |
| boolean | Disable download button for this collection. |
| boolean | Run exports synchronously for this collection. |
| boolean | Disable save button for this collection. |
| string | Force format ( |
| object | Lifecycle hooks — |
| `number \ | function` | Maximum documents to export. Set to |
| function | Override the export collection config for this specific target. |
ImportConfig Options
Property | Type | Description |
|---|---|---|
| number | Documents per batch during import. Default: |
| string | Default status for imported docs ( |
| boolean | Run imports synchronously for this collection. |
| object | Lifecycle hooks — |
| `number \ | function` | Maximum documents to import. Set to |
| function | Override the import collection config for this specific target. |
Example Configuration
1
import { importExportPlugin } from '@payloadcms/plugin-import-export'
2
3
export default buildConfig({
4
plugins: [
5
importExportPlugin({
6
debug: true,
7
8
// Global limits (0 = unlimited, which is the default)
9
exportLimit: 10000,
10
importLimit: 5000,
11
12
// Override default export collection (e.g., add access control)
13
// This will be used by all collections unless they further override the config
14
overrideExportCollection: ({ collection }) => {
15
collection.access = {
16
...collection.access,
17
read: ({ req }) => req.user?.role === 'admin',
18
}
19
return collection
20
},
21
22
// Per-collection settings
23
collections: [
24
{
25
slug: 'pages',
26
export: {
27
format: 'csv',
28
disableDownload: true,
29
limit: 1000, // Override global exportLimit for this collection
30
},
31
import: {
32
defaultVersionStatus: 'draft',
33
limit: 500, // Override global importLimit for this collection
34
},
35
},
36
{
37
slug: 'posts',
38
export: false, // Disable export for posts
39
},
40
],
41
}),
42
],
43
})
Collection Visibility
The exports and imports collections are hidden from the admin navigation by default (admin.group: false). Their routes remain accessible (for example /admin/collections/exports and /admin/collections/imports), so you can open them directly or link to them from your app. To list them in the sidebar, use overrideExportCollection and overrideImportCollection to set a group:
1
import { importExportPlugin } from '@payloadcms/plugin-import-export'
2
3
importExportPlugin({
4
overrideExportCollection: ({ collection }) => ({
5
...collection,
6
admin: {
7
...collection.admin,
8
group: 'Data Management',
9
},
10
}),
11
overrideImportCollection: ({ collection }) => ({
12
...collection,
13
admin: {
14
...collection.admin,
15
group: 'Data Management',
16
},
17
}),
18
collections: [{ slug: 'pages' }],
19
})
With a group set, the Exports and Imports collections appear in the admin navigation under "Data Management", and you can open saved exports or import documents from there (including downloading saved export files).
Limiting Import and Export Size
You can limit the number of documents that can be imported or exported in a single operation. This helps prevent DDOS-style abuse and protects server resources during large data operations.
Limits can be set globally via exportLimit and importLimit, or per-collection using the limit option in export/import config. Per-collection limits take precedence over global limits. Set to 0 for unlimited (the default).
Dynamic Limits
Limits can be a function that receives the request context, allowing dynamic limits based on user roles or other factors:
1
importExportPlugin({
2
// Dynamic global limit based on user role
3
exportLimit: ({ req }) => {
4
return req.user?.role === 'admin' ? 50000 : 1000
5
},
6
7
collections: [
8
{
9
slug: 'sensitive-data',
10
import: {
11
// Per-collection dynamic limit
12
limit: ({ req }) => {
13
if (req.user?.subscription === 'enterprise') return 100000
14
if (req.user?.subscription === 'pro') return 10000
15
return 1000
16
},
17
},
18
},
19
],
20
})
Collection-Specific Import and Export targets
By default, the plugin creates a single exports collection and a single imports collection that handle all import/export operations across your enabled collections. However, you can create separate import and export targets for specific collections by overriding the collection slug.
When you change the slug using the overrideCollection function at the per-collection level, this creates an entirely separate uploads collection for that specific source collection. This is useful when you need:
- Different access control rules for different data types
- Separate storage locations for exports
- Isolated import queues for specific workflows
- Different admin UI organization
Example: Separate Export Targets
1
import { importExportPlugin } from '@payloadcms/plugin-import-export'
2
3
export default buildConfig({
4
plugins: [
5
importExportPlugin({
6
collections: [
7
{
8
slug: 'users',
9
export: {
10
// Create a separate 'user-exports' collection for user data
11
overrideCollection: ({ collection }) => {
12
return {
13
...collection,
14
slug: 'user-exports',
15
labels: {
16
singular: 'User Export',
17
plural: 'User Exports',
18
},
19
access: {
20
// Only super admins can access user exports
21
read: ({ req }) => req.user?.role === 'superadmin',
22
create: ({ req }) => req.user?.role === 'superadmin',
23
},
24
}
25
},
26
},
27
import: {
28
// Create a separate 'user-imports' collection
29
overrideCollection: ({ collection }) => {
30
return {
31
...collection,
32
slug: 'user-imports',
33
labels: {
34
singular: 'User Import',
35
plural: 'User Imports',
36
},
37
access: {
38
read: ({ req }) => req.user?.role === 'superadmin',
39
create: ({ req }) => req.user?.role === 'superadmin',
40
},
41
}
42
},
43
},
44
},
45
{
46
slug: 'pages',
47
// Pages will use the default 'exports' and 'imports' collections
48
},
49
{
50
slug: 'posts',
51
// Posts will also use the default collections
52
},
53
],
54
}),
55
],
56
})
In this example:
- User exports are stored in
user-exportscollection with restricted access - User imports are tracked in
user-importscollection - Pages and posts share the default
exportsandimportscollections
Combining Top-Level and Per-Collection Overrides
You can combine the top-level overrideExportCollection / overrideImportCollection functions with per-collection overrides. The top-level override is applied first, then the per-collection override:
1
importExportPlugin({
2
// Apply to ALL export collections (both default and custom slugs)
3
overrideExportCollection: ({ collection }) => {
4
return {
5
...collection,
6
admin: {
7
...collection.admin,
8
group: 'Data Management',
9
},
10
}
11
},
12
13
collections: [
14
{
15
slug: 'sensitive-data',
16
export: {
17
// This override is applied AFTER the top-level override
18
overrideCollection: ({ collection }) => {
19
return {
20
...collection,
21
slug: 'sensitive-exports',
22
access: {
23
read: () => false, // Completely restrict read access
24
create: ({ req }) => req.user?.role === 'admin',
25
},
26
}
27
},
28
},
29
},
30
],
31
})
Hooks
Collection-level hooks let you intercept each batch of documents before it is written (to file on export, or to the database on import) and after it has been written. Hooks fire once per batch and work for both csv and json formats.
Hook arguments
All hooks receive:
Argument | Type | Description |
|---|---|---|
| number | Current batch, starting at |
| | Transformed batch — flat rows for CSV export, nested docs otherwise. |
| string | Export/import format. Open-ended (`'csv' \ | 'json' \ | string`). |
| array | Source data before transformation. Read-only — do not mutate. |
| | The full request object. |
| number | Total number of batches in this operation. |
ImportAfterHook additionally receives result: ImportResult (per-batch counts and errors) instead of data/originalData.
before hooks — modify data
before hooks return the (optionally modified) data array, which replaces the batch going into the write step. Returning an empty array skips the write for that batch without aborting remaining batches.
1
import { importExportPlugin } from '@payloadcms/plugin-import-export'
2
3
importExportPlugin({
4
collections: [
5
{
6
slug: 'users',
7
export: {
8
hooks: {
9
// Mask sensitive fields before the batch is written to file
10
before: ({ data, format }) => {
11
return data.map((row) => {
12
const { passwordHash: _ph, ssn: _ssn, ...safe } = row
13
return safe
14
})
15
},
16
},
17
},
18
import: {
19
hooks: {
20
// Normalise incoming data before it is written to the database
21
before: ({ data }) => {
22
return data.map((doc) => ({
23
...doc,
24
email:
25
typeof doc.email === 'string'
26
? doc.email.toLowerCase()
27
: doc.email,
28
}))
29
},
30
},
31
},
32
},
33
],
34
})
after hooks — logging and observability
after hooks fire after the write has completed. Their return value is ignored — use them for logging, metrics, or notifications.
1
importExportPlugin({
2
collections: [
3
{
4
slug: 'orders',
5
export: {
6
hooks: {
7
after: ({ batchNumber, totalBatches, data, format, req }) => {
8
req.payload.logger.info({
9
msg: `Export batch ${batchNumber}/${totalBatches} written`,
10
format,
11
docsInBatch: data.length,
12
})
13
},
14
},
15
},
16
import: {
17
hooks: {
18
after: ({ batchNumber, totalBatches, result, req }) => {
19
req.payload.logger.info({
20
msg: `Import batch ${batchNumber}/${totalBatches} complete`,
21
imported: result.imported,
22
updated: result.updated,
23
errors: result.errors.length,
24
})
25
},
26
},
27
},
28
},
29
],
30
})
Using originalData for context
originalData gives you the raw source before any transformation. For exports it is the original DB documents; for imports it is the raw parsed file rows. This is useful when you need context from the full document while building modified flat rows.
1
export: {
2
hooks: {
3
before: ({ data, originalData }) => {
4
return data.map((row, i) => ({
5
...row,
6
// Add a computed column not present in the DB document
7
displayName: `${originalData[i]?.firstName} ${originalData[i]?.lastName}`,
8
}))
9
},
10
},
11
},
Column name mapping for foreign systems
When importing from or exporting to a foreign system, column names rarely match your Payload field names. Use the batch before hooks to rename keys on the way in or out.
Exporting with renamed CSV columns
Use export.hooks.before to rewrite every row's keys to the foreign system's column names. The returned shape is what gets written to the file.
1
import { importExportPlugin } from '@payloadcms/plugin-import-export'
2
3
const exportRenameMap: Record<string, string> = {
4
title: 'Post Title',
5
excerpt: 'Summary',
6
count: 'View Count',
7
}
8
9
importExportPlugin({
10
collections: [
11
{
12
slug: 'posts',
13
export: {
14
hooks: {
15
before: ({ data }) =>
16
data.map((row) => {
17
const renamed: Record<string, unknown> = {}
18
for (const [key, value] of Object.entries(row)) {
19
renamed[exportRenameMap[key] ?? key] = value
20
}
21
return renamed
22
}),
23
},
24
},
25
},
26
],
27
})
JSON exports work the same way — the hook receives the fully-transformed batch, and the returned keys become the top-level JSON keys.
Importing from foreign CSV columns
Use import.hooks.before to rewrite incoming keys back to Payload field names. The hook receives already-unflattened documents, so foreign top-level keys like Post Title are still present and can be remapped to title before the DB write. Keys you don't include in the returned object are dropped.
1
const importRenameMap: Record<string, string> = {
2
'Post Title': 'title',
3
Summary: 'excerpt',
4
'View Count': 'count',
5
}
6
7
importExportPlugin({
8
collections: [
9
{
10
slug: 'posts',
11
import: {
12
hooks: {
13
before: ({ data }) =>
14
data.map((doc) => {
15
const renamed: Record<string, unknown> = {}
16
for (const [key, value] of Object.entries(doc)) {
17
const payloadKey = importRenameMap[key]
18
if (payloadKey) {
19
renamed[payloadKey] = value
20
}
21
// Foreign keys not present in the rename map are dropped.
22
}
23
return renamed
24
}),
25
},
26
},
27
},
28
],
29
})
CSV cell values arrive as strings. Payload coerces basic scalar types automatically on write, but if a target field has stricter validation you can coerce inside the hook (renamed.count = Number(value)).
Field-level export rename for shared fields
When a field definition is shared across collections and the rename should travel with the field, use the field's own hooks.beforeExport. Mutate siblingData to add the renamed key and return undefined so the original field key is dropped from the output:
1
import type { FieldBeforeExportHook } from '@payloadcms/plugin-import-export'
2
3
const sharedNameField = {
4
name: 'sharedName',
5
type: 'text' as const,
6
custom: {
7
'plugin-import-export': {
8
hooks: {
9
beforeExport: (({ siblingData, value }) => {
10
siblingData['Display Name'] = value
11
return undefined
12
}) satisfies FieldBeforeExportHook,
13
},
14
},
15
},
16
}
This pattern is export-only. Field-level hooks.beforeImport does not fire for foreign columns — it's keyed by the incoming column name, so it can't pick up a column whose name doesn't already match a Payload field. For the reverse direction, use the collection-level import.hooks.before recipe above.
Field Options
In addition to collection-level hooks, you can configure field-level export and import behavior directly on any field's custom['plugin-import-export'] config. This is especially useful when:
- You share a field definition across multiple collections and want the behavior to travel with the field
- You need to transform a deeply nested field without navigating the full document structure in a collection-level hook
Property | Type | Description |
|---|---|---|
| boolean | When |
| function | Runs before a field value is exported. Works for CSV and JSON. |
| function | Runs before a field value is imported. Works for CSV and JSON. |
| function | Deprecated — use |
| function | Deprecated — use |
Disabling Fields
To completely exclude a field from import and export operations:
1
{
2
name: 'internalField',
3
type: 'text',
4
custom: {
5
'plugin-import-export': {
6
disabled: true,
7
},
8
},
9
}
When a field is disabled:
- It will not appear in export CSV/JSON files
- It will be ignored during import operations
- Nested fields inside disabled parent fields are also excluded
hooks.beforeExport
Use hooks.beforeExport to transform a field's value before it is exported. Works for both csv and json formats.
The beforeExport function receives:
Property | Type | Description |
|---|---|---|
| string | Column/field path, underscore-separated for nested fields (includes array indices). |
| object | The top-level document being exported. |
| string | |
| object | Writable output at the current level. CSV: the flat row accumulator. JSON: the sibling output object. |
| object | Read-only source at the current level, before any transformation. Use this to read another sibling's raw value. |
| unknown | The field value from the source document. |
Return a value to replace the field, undefined to use default behavior, or mutate siblingData to add extra columns at the same level.
Example — splitting a relationship into multiple columns:
1
import type { FieldBeforeExportHook } from '@payloadcms/plugin-import-export'
2
3
const authorFieldWithHooks = {
4
name: 'author',
5
type: 'relationship',
6
relationTo: 'users',
7
custom: {
8
'plugin-import-export': {
9
hooks: {
10
beforeExport: (({ value, columnName, siblingData, format }) => {
11
if (
12
format === 'csv' &&
13
value &&
14
typeof value === 'object' &&
15
'id' in value &&
16
'email' in value
17
) {
18
siblingData[`${columnName}_id`] = (
19
value as { id: number | string }
20
).id
21
siblingData[`${columnName}_email`] = (
22
value as { email: string }
23
).email
24
return undefined
25
}
26
return value
27
}) satisfies FieldBeforeExportHook,
28
},
29
},
30
},
31
}
Because the hook is defined on the field itself, you can share authorFieldWithHooks across multiple collections and each will get the same export behavior automatically.
hooks.beforeImport
Use hooks.beforeImport to transform a field's value before it is imported. Works for both csv and json formats.
The beforeImport function receives:
Property | Type | Description |
|---|---|---|
| string | Column/field path. |
| object | The full flat row (CSV) or top-level parsed document (JSON) being imported. |
| string | |
| object | Data at the current level. CSV: same reference as |
| object | Read-only source at the current level, before any transformation. CSV: same as |
| unknown | The raw value from the import file. |
Return the transformed value, undefined to skip, or null to explicitly set null.
1
import type { FieldBeforeImportHook } from '@payloadcms/plugin-import-export'
2
3
{
4
name: 'author',
5
type: 'relationship',
6
relationTo: 'users',
7
custom: {
8
'plugin-import-export': {
9
hooks: {
10
beforeImport: (({ value, columnName, data, format }) => {
11
if (format === 'csv') {
12
const id = data[`${columnName}_id`]
13
return id ?? undefined
14
}
15
return value
16
}) satisfies FieldBeforeImportHook,
17
},
18
},
19
},
20
}
Execution Order
Field-level hooks run before collection-level hooks:
- Field-level
hooks.beforeExport/hooks.beforeImport: run per-field, per-document, during transformation - Collection-level
export.hooks.before/import.hooks.before: run per-batch, on the already-field-transformed data
Migrating from toCSV / fromCSV
toCSV and fromCSV are deprecated and will be removed in v4. Existing hooks continue to work unchanged. New code should use hooks.beforeExport / hooks.beforeImport, which also run for JSON exports and imports.
1
// Before
2
custom: {
3
'plugin-import-export': {
4
toCSV: ({ value, columnName, row, doc }) => {
5
row[`${columnName}_id`] = (value as any).id
6
return doc.title
7
},
8
fromCSV: ({ value, data }) => data[`${value}_key`],
9
},
10
},
11
12
// After
13
custom: {
14
'plugin-import-export': {
15
hooks: {
16
beforeExport: ({ value, columnName, siblingData, data, format }) => {
17
siblingData[`${columnName}_id`] = (value as any).id
18
return data.title
19
},
20
beforeImport: ({ value, data, format }) => data[`${value}_key`],
21
},
22
},
23
},
Virtual Fields
Virtual fields (fields with virtual: true) are handled differently during import and export:
- Export: Virtual fields ARE included in exports. They contain computed values from hooks.
- Import: Virtual fields are SKIPPED during import. Since they're computed, they cannot be imported.
Exporting Data
There are four possible ways that the plugin allows for exporting documents, the first two are available in the admin UI from the list view of a collection:
- Direct download - Using a
POSTto/api/exports/downloadand streams the response as a file download - File storage - Goes to the
exportscollection as an uploads enabled collection - Local API - A create call to the exports collection:
payload.create({ collection: 'exports', data: { collectionSlug: 'pages', format: 'json' } }) - Jobs Queue -
payload.jobs.queue({ task: 'createCollectionExport', input: parameters })
In the Export drawer you can choose:
- Download — Streams the export file directly to the browser without saving. Nothing is stored in the exports collection.
- Save — Creates a document in the exports collection (an upload) so the export is stored and can be reused or downloaded later.
To download a saved export, open the exports collection (go to /admin/collections/exports or, if you made it visible as in Collection Visibility, use the sidebar), open the export document, and use the file download from there. Either the Download or Save option can be disabled per collection via ExportConfig (disableDownload, disableSave).
The UI for creating exports provides options so that users can be selective about which documents to include and also which columns or fields to include.
Selection Modes
When opening the export drawer from a collection's list view, you can choose which documents to export:
Mode | Description |
|---|---|
Use all documents | Export the entire collection (respects any limit you set) |
Use current filters | Export only documents matching your active list view filters |
Use current selection | Export only the documents you've checked in the list view |
It is necessary to add access control to the uploads collection configuration using the overrideExportCollection function if you have enabled this plugin on collections with data that some authenticated users should not have access to.
The following parameters are used by the export function to handle requests:
Property | Type | Description |
|---|---|---|
| string | Either |
| number | The max number of documents to export. Leave empty to export all matching documents. |
| number | The page of documents to start from (used with limit for pagination). |
| string | The field to use for ordering documents (e.g., |
| number | How deeply to populate relationships. Default: |
| string | The locale code to query documents or |
| boolean | When |
| string[] | Which collection fields to include in the export. Defaults to all fields. |
| string | The collection slug to export from. |
| object | The WhereObject used to query documents to export. This is set by making selections or filters from the list view |
| string | The name for the exported file (without extension). |
Importing Data
The plugin allows importing data from CSV or JSON files. There are several ways to import:
- Admin UI - Use the Import drawer from the list view of a collection
- File storage - Create an import document in the
importscollection with an uploaded file - Local API - Create an import document:
payload.create({ collection: 'imports', data: { collectionSlug: 'pages', importMode: 'create' }, file: { ... } }) - Jobs Queue -
payload.jobs.queue({ task: 'createCollectionImport', input: parameters })
Import Parameters
Property | Type | Description |
|---|---|---|
| string | The collection to import into. |
| string | |
| string | The field to use for matching existing documents during |
| string | The locale to use for localized fields. |
The matchField option allows you to match documents by a field other than id. For example, if importing users, you could match by email instead of id:
1
payload.create({
2
collection: 'imports',
3
data: {
4
collectionSlug: 'users',
5
importMode: 'upsert',
6
matchField: 'email',
7
},
8
file: csvFile,
9
})
Import Modes
Mode | Description |
|---|---|
create | Only creates new documents. Documents with existing IDs will fail. |
update | Only updates existing documents. Requires |
upsert | Creates new documents or updates existing ones based on |
Import Results
After an import completes, the import document is updated with a summary:
Property | Type | Description |
|---|---|---|
| string | |
| number | Total number of rows processed |
| number | Number of successfully imported documents |
| number | Number of updated documents (update/upsert modes) |
| number | Number of rows that failed |
| array | Details about each failure |
CSV Format
Column Naming Convention
CSV columns use underscore (_) notation to represent nested fields:
Field Path | CSV Column Name |
|---|---|
| |
| |
| |
| |
| |
Relationship Columns
For relationship fields, the column format varies based on the relationship type:
Relationship Type | Column(s) |
|---|---|
hasOne (monomorphic) | |
hasOne (polymorphic) | |
hasMany (monomorphic) | |
hasMany (polymorphic) | |
Value Handling
During CSV import, certain values are automatically converted:
CSV Value | Converted To | Notes |
|---|---|---|
| | Case-insensitive |
| | Case-insensitive |
| | Use |
Empty string | | Depends on field type |
Numeric strings | | Auto-detected for integers and floats |
To preserve literal strings like "null" or "true", use a fromCSV function:
1
{
2
name: 'specialField',
3
type: 'text',
4
custom: {
5
'plugin-import-export': {
6
fromCSV: ({ value }) => {
7
// Return raw value without automatic conversion
8
return value
9
},
10
},
11
},
12
}
Localized Fields
Single Locale Export
When exporting with a specific locale selected, localized fields appear without a locale suffix:
1
title,description
2
"English Title","English Description"
Multi-Locale Export
When exporting with locale set to all, each localized field gets a column per configured locale:
1
title_en,title_es,title_de,description_en,description_es,description_de
2
"English","Español","Deutsch","Desc EN","Desc ES","Desc DE"
Importing Localized Fields
For single-locale import, data goes into the locale specified in the import settings:
1
title,description
2
"New Title","New Description"
For multi-locale import, use locale suffixes in column names to import multiple locales at once:
1
title_en,title_es
2
"English Title","Título en Español"
JSON Format
When using JSON format for import/export:
- Export: Documents are exported as a JSON array, preserving their nested structure
- Import: Expects a JSON array of document objects
JSON format preserves the exact structure of your data, including:
- Nested objects and arrays
- Rich text (Lexical) structures with numeric properties
- Relationship references
- All field types in their native format
Example JSON export:
1
[
2
{
3
"id": "abc123",
4
"title": "My Page",
5
"group": {
6
"value": "nested value",
7
"array": [{ "field1": "item 1" }, { "field2": "item 2" }]
8
},
9
"blocks": [
10
{
11
"blockType": "hero",
12
"title": "Hero Title"
13
}
14
]
15
}
16
]