Import custom field values

Importing custom field values rely on the exact same XLSX format as provided by the export, so you may use an exported file directly as the source for import. Except for the required A and B columns, you may remove any columns from C and forward as you see fit, but, if present, the header value must match a defined field name for the type. The same applies to rows - only objects directly referenced by an _id value is considered for updates, making it possible to do fast, partial updates. Shop or Global level imports don't use the _id field but will always update the provided columns with custom fields for the shop being imported into.

Imports run in the background. You can safely leave the page while the import runs, but you are encouraged not to make any changes to the custom fields while the import runs. If you start additional import jobs, the data will be added to the import queue and imported in the order of upload.

Consideration for repeatable field values

To provide multiple values for a custom field defined as a repeatable field, you need to format this carefully. ACF exports and imports values for repeatable fields in an "array" notation starting with an opening square bracket ( [ ) followed by a quoted and comma-separated list of values and then a closing square bracket ( ] ). Examples:

["1", "2", "3"]
["John", "Stacey"]

for three values 1, 2 and 3, two values "John" and "Stacey" and a single value "Awesome" respectively (note that a single value can also be stated without square brackets).

Considerations for HTML fields

You can import HTML content to HTML fields just like any other piece of data, but there is also an option to import Markdown content directly to an HTML field. This comes in handy if you want to data from Markdown fields (or Markdown from a different source) to a new HTML field. All you need to do is to prefix the Markdown content with the tag <markdown> as shown here

- list item 1
- list item 2

The ACF importer will grab the Markdown content after the initial tag and render it as HTML before importing it. Note that the same applies to repeatable HTML values as outlined above

Considerations for multi-language fields

Multi-language fields are structured in JSON objects with the individual language locales as keys. It is important to adhere to the provided format when importing content for the languages. Examples:

  "en": "Goodnight", 
  "de": "Guten Abend"

Each of the keys ( "en" and "de" in the above example) must match the selected ISO locales set up for your multi-language content for the text to show up in ACF. Note, that if your multi-language field is also a repeatable field, the above format will be in an array like this:

  "en": "Goodnight", 
  "de": "Guten Abend"
  "en": "Good morning", 
  "de": "Guten Morgen"

When manually editing content for each language in an import file, please ensure that any double quotes are "escaped", i.e. prefixed by a backslash:

 "en": "My name is \"Boss\"",
 "de": "Mein Name ist \"Boss\"" 

Considerations for bulk uploading media files

An import file can also bulk upload medias to both Media v1 and v2 type fields. If you provide publicly available urls as the value (full HTTP/HTTPS url), the referenced media will be copied to ACF's secure data storage bucket and the new url to the uploaded media will be stored in the corresponding metafield. If you want to delete a media, clear the field's value in the import file. When uploading medias in bulk to a repeatable Media v1 field, you will need to provide the urls as a JSON array with each occurrence listed inside the array: To load 4 occurrences of a media:

["url", "url", "url", "url"]

When uploading medias in bulk to a repeatable Media v2 field, you will need to provide the urls as a JSON array of arrays, so to load 4 occurrences of two medias each:

 [["url", "url"], ["url", "url"], ["url", "url"], ["url", "url"]]

Last updated