Metafields are Shopify's way of storing extra product information that doesn't fit the standard columns — fabric composition, care instructions, nutritional facts, country of origin, warranty length. If your catalog relies on metafields, moving that data anywhere else requires understanding where it lives and how it survives an export. This guide explains the mechanics and how to handle metafield data when working with CSV files.
What metafields are
A metafield is a key-value pair attached to a product (or variant). Where the standard export has fixed columns like Title and Variant Price, metafields are dynamic: one store might define fabric.care_instructions, another food.allergens. Each metafield has a namespace, a key, a type (text, number, URL, JSON) and a value.
In the Shopify admin, metafields are managed per definition. In a CSV export, their behavior depends on how the export was produced.
How metafields appear in CSV exports
The classic product export does not include metafield values as columns. There are two ways stores get metafield data into CSV:
- Dedicated metafield export apps — these produce files where each metafield definition becomes a column, keyed by namespace and key (for example
custom.care_instructions), with one row per product. - Shopify's newer export flows — some include metafield columns appended after the standard set.
Either way, the pattern to recognize is the same: metafield columns are named by their definition, and each row carries the value for that product or variant. Variant-level metafields repeat on every variant row, just like standard variant columns.
The import side: getting metafields back in
Importing metafields via CSV requires the same column naming the export used, plus a matching metafield definition in the store. Common failures:
- Definition missing — if the store has no metafield definition for
custom.care_instructions, the import either creates an unstructured field or drops the value. - Type mismatch — a metafield defined as integer receiving "about 5" will reject the row.
- Wrong namespace —
care_instructionsandcustom.care_instructionsare different keys.
The safe workflow is: export from the source store, keep the metafield column names exactly, create matching definitions in the target store, then import.
Metafields and platform conversion
When converting a catalog to another platform — for example to the Hyperzod import structure — metafields need a decision, because the target format has fixed columns rather than dynamic ones:
- Map to a standard column. A metafield like
custom.short_descriptionmaps naturally toPRODUCT.DESCRIPTION. - Map to tags. Facts like
custom.dietary(veg/non-veg) can becomePRODUCT.TAGSvalues. - Append to description. Long-tail facts (care instructions, ingredients) can be appended under the description so the information survives the move.
- Drop deliberately. Internal metafields that only mattered to the old platform's apps can be excluded on purpose.
Doing this by hand means writing formulas for every metafield column. With CSV Pilot you describe the mapping in the chat — "put the care_instructions metafield at the end of the description, and turn the dietary metafield into a veg/non-veg tag" — and the conversion applies it across the catalog. The preview shows the result per product before export.
A checklist for metafield work
- Export with a tool that includes metafield columns, and keep the original.
- List every metafield definition and decide: map, tag, append, or drop.
- Create matching definitions in the target store before importing anything back.
- Validate types — text stays text, numbers stay numbers.
- Spot-check five products after import, including one with empty metafield values.
Metafields are where a store's unique data lives. Treat them as a mapping exercise rather than a copy-paste, and they survive any platform move intact.