How to bulk import metafields in Shopify with a CSV

Q: What does the metafield CSV column header look like?

Metafield: namespace.key [type] — for example Metafield: custom.care_guide [single_line_text_field]. The namespace, key, and type must match an existing product metafield definition in your store, or the values will not import.

Updated July 2026

Migrating from another platform, backfilling a new field across the catalog, or loading spec data a supplier sent as a spreadsheet — sometimes metafield values start life in a CSV. Shopify’s native product importer can load them, and for a one-off migration it is a reasonable tool. This guide covers the exact column format, the step-by-step workflow, and the traps — then when a CSV is the wrong tool for the job.

The metafield column format

The product CSV supports metafields through specially named columns. The header is:

Metafield: namespace.key [type]

For example, a defined single-line text metafield custom.care_guide gets the column header Metafield: custom.care_guide [single_line_text_field]. Three things have to line up:

A product metafield definition must exist (Settings → Custom data → Products) with exactly that namespace and key. Create the definition first — the importer will not invent one for you.
The type in brackets must match the definition — single_line_text_field, multi_line_text_field, number_integer, boolean, and so on.
Each row’s value must be valid for that type. Text in a number column or “yes” in a boolean column is rejected for that product.

Step by step

Create the metafield definition in Settings → Custom data → Products, with the type your theme expects.
Export your products (Products → Export) so the file has the correct Handle for every product — the importer matches rows to products by handle.
Add the metafield column with the header format above and fill in the values. You can delete the columns you are not changing — a slimmer file means fewer accidental edits.
Import it (Products → Import) and tick Overwrite products with matching handles — without it, existing products are skipped and no metafields change.
Read the results email. Per-row failures — type rejections, validation errors — are reported there, not on screen. Then spot-check values in the admin, because the email is the only receipt you get.

Where CSV metafield imports bite

No preview, no undo. The import writes whatever is in the file. Overwrite 400 care guides with a broken column and the previous values are simply gone — Shopify keeps no history for metafield values.
Overwrite semantics are all-or-nothing per column. An empty cell in a metafield column can clear the existing value on that product — a half-filled column is a quiet way to wipe data you meant to keep.
Spreadsheets mangle values. List and JSON types need exact formatting in the cell; Excel’s smart quotes, re-encoded characters, and date “help” are classic ways for a valid file to stop being valid.
Product-level only. Variant metafields never import through the product CSV.
Failures are itemized after the fact in the results email — there is no dry run. On a big file you find out what broke only once it has broken.

CSV import vs. an in-admin bulk editor

The dividing line is one-off vs. operational. A migration — values already living in a spreadsheet, run once, checked once — is what the CSV importer is for. But most metafield work after launch is operational: set custom.shipping_note on everything from one vendor, fix the care guide on 200 products, clear a stale badge field. Round-tripping those through export → edit → import means no preview, no undo, and a results email as your only verification — for an edit a rule-based tool applies in one pass. Our guide to bulk editing product metafields covers that workflow end to end.

Doing this with SureEdit

SureEdit (Growth plan, 7-day free trial) is the operational half of this story: instead of building a file, you filter to the exact products, set the metafield value once, and preview every before → after value before anything is written. Each write is re-read and verified, rejections are itemized with the reason, and the original values are journaled — so a bad bulk write is one click to undo, not a restore-from-backup project. If the values genuinely start in a spreadsheet, import once with the CSV — then do the ongoing edits where you can see them.

Try SureEdit — free plan available

FAQ

What does the metafield CSV column header look like?
Metafield: namespace.key [type] — for example Metafield: custom.care_guide [single_line_text_field]. The namespace, key, and type must match an existing product metafield definition in your store, or the values will not import.

Can I export my existing metafield values to CSV first?
Shopify’s standard product export does not include metafield columns, which makes before/after comparison awkward. To see current values before an import, check them in the admin bulk editor’s metafield columns, or use a tool that reads and journals values for you.

Can the product CSV import variant metafields?
No. Metafield columns in the product CSV are product-level only. Variant metafields need the Shopify API or a dedicated import app — the product importer will not touch them.

Related guides

← All guides