Importing & Updating Metafield Data

Quick Start

The fastest way to get started importing metafield data using Custom Fields is to start with an export or start with a sample file from the app. Either way, the file will be properly formatted, saving hassles and time.

Start with an export

For best results, be sure to have some fields configured and with at least one object with data in each field. 

In the app:

  • In the left sidebar, click on Export under the object type you'd like to (eventually) import (example: under Products).
  • Apply Export Filters as needed to limit the export file size.
  • Choose File Format
    • Standard Format creates one column per metafield. Ideal for simple data.
    • Flat Data creates one row per data point. Ideal for complex data (Widgets, JSON, etc). 

Start with a sample CSV file

In the app:

  • In the left sidebar, click on Import under the object type you'd like to import (example: under Products)
  • Click on Help in the content area.
  • Click on Download Sample CSV file.

Note: Object IDs in sample data are not valid IDs. Column names are valid.

Running an Import

In the app:

  • In the left sidebar, click on Import under the object type you'd like to import (example, under Products).
  • Upload your CSV with updated data.

Deleting Metafield Values 

Use   DELETE (in all caps) as the cell value to delete existing content. Blank cells in a CSV are ignored, not deleted.

This App Updates Metafields Only

Export files often include additional columns, such as Order Name, Product Title and many others.  Custom Fields only imports or updates metafield data. 

Supported Objects & Data Types

Shopify Objects
The Custom Fields app can import metafield data into the most common object types in Shopify. These include:

  • Product Metafields
  • Page Metafields
  • Blog Post/Article Metafields
  • Order Metafields
  • Draft Order Metafields
  • Customer Metafields

Data Types
The Custom Fields app is capable of importing and validating any type of metafield data, including all metafield data types in the Shopify API including...

  • Legacy Metafield Types
    • string
    • integer
    • json
  • All New Metafield Types
    • boolean
    • color
    • date
    • date_time
    • dimension
    • file_reference
    • json
    • multi_line_text_field
    • number_decimal
    • number_integer
    • page_reference
    • rating
    • single_line_text_field
    • url
    • variant_reference
    • volume
    • weight
  • Custom Fields App-Specific Types
    • Widget data
    • Advanced field types 

Defined & Undefined Fields

The Custom Fields app automatically synchronizes field configurations for any metafield Definitions that exist in your Shopify store. Synchronized field Definitions are then recognized by the importer.

App Configured & Un-configured Fields

Importing data using Custom Fields no longer requires each field be configured in the app first. As long as the column header uses the proper naming syntax, any metafield data can be imported.

Formatting Metafield Column Names

Use the following formula for column names:  namespace["key"]:metafield_type

Example:  custom_fields["my_text"]:string

A complete list of valid metafield types can be found in the Type column in Shopify's Metafield Type documentation, found here: https://shopify.dev/apps/metafields/types#supported-types

For widgets, use  json_string
Example: custom_fields["my_widget"]:json_string

For lists of data, use list.metafield_type
Example:  custom_fields["my_reference"]:list.product_reference

Creating your own import file from scratch in Standard Format

Each supported Shopify object type has slightly different requirements. 

Product Metafields

The CSV file to import product metafield data must have the following columns:

  • A non-empty Title column
    • Used to determine if the item is a product or a variant. Actual title ignored.
  • An identifier
    • Handle 
      • Used to look up the Product ID during import. Less efficient, slows import. Ignored if Product ID is present.
    • ID
      • Product ID used to find the product. Most efficient, speeds import, avoids issues with changing handles (product URLs).
  • One or more columns with metafield data
    • A metafield's namespace and key, followed by the metafield type.
      • Example: custom_fields["my_text"]:string

All Other Metafields

  • Blog Posts
  • Orders
  • Draft Orders
  • Customers

Must have the following columns:

  • ID
    • ID used to find the object, such as a page ID.
  • One or more columns with metafield data
    • A metafield's namespace and key, followed by the metafield type.
      • Example: custom_fields["my_text"]:string

Improving Import Speed

Apps are limited by Shopify to two API calls per second per customer. Import speed depends largely on how much metafield data is in the import file. All non-blank metafield data is set to Shopify, even if the data has not changed.

To speed up imports
Limit the metafield columns and the number of objects in the import file.

When importing product metafields, include the product ID rather than just the product's handle. Handles can be used but slow down the import process if only the handle is provided.

Related Articles