SHOPIFY PRODUCT METAFIELD CSV GUIDE
Shopify CSV metafields not importing? Check these 7 things
When a product metafield stays blank or an import reports an invalid value, the CSV may name the wrong field, use an unsupported resource, format a typed value incorrectly, or update the wrong product. Start with a current export—not a header copied from another store.
Check CSV structure privatelyQUICK ANSWER
Define the product metafield, preserve its exported header, enter a value that matches its type, and preview one matching product.
Use the target store’s current CSV to obtain its field identifiers.
Retain the metafield column and update only the intended product rows.
Confirm the matching product and value before a broad overwrite.
METAFIELD IMPORT CHECKS
What each result usually means
Column is missing from a fresh exportThe product metafield has not been defined for this store
Shopify adds a product metafield to the product CSV export after that metafield has been defined. A label from another store, an app, or a spreadsheet does not by itself create a usable definition in the target store. Definitions also provide validation rules for values.
In Shopify admin, confirm the product metafield definition and its type in the target store. Then export one target product and use that export as the update file’s starting point. Keep a backup before adding columns or enabling overwrite.
Metafield column was ignored or rejectedThe header does not name the product metafield’s namespace and key
Shopify’s current product CSV uses product metafield identifiers such as product.metafields.custom.fabric. An exported header can also include a human-readable name, for example Fabric (product.metafields.custom.fabric). The namespace and key—not the visible label—identify the field.
Copy the complete column header from a fresh export of the same store. Do not rename it, replace parentheses, or swap in a display name from the metafield editor. Check for duplicate columns that point to the same namespace and key.
Product import succeeds, but a variant metafield remains unchangedThe CSV workflow supports product metafields, not variant metafields
Shopify documents product metafields for product CSV import and export, while variant metafields are not supported in that product CSV workflow. Adding a variant-looking column to a product import will not turn it into a supported variant metafield update.
For a value owned by a variant, use Shopify’s variant bulk editor or another supported variant workflow. First confirm the resource owner in the metafield definition; use the product CSV only for product-level metafields.
Value must match the metafield definitionThe cell’s format does not match the metafield type
A metafield can be text, a number, date, color, URL, measurement, money, a list, or a reference. A value that looks reasonable in a spreadsheet can still fail the definition’s validation. For example, Shopify’s CSV guidance uses values such as #ff00cc for a color and semicolons between items in a supported list.
Read the definition’s type and validation rules before editing the cell. Use the current exported value or Shopify’s documented example as the format reference. Save actual values rather than spreadsheet formulas, and inspect the exported CSV rather than only the spreadsheet view.
Reference value is invalid or cannot be foundA product or metaobject reference does not identify an available record
Reference metafields use resource identifiers rather than display names. Shopify documents product and metaobject reference values using a resource GID or a handle, with semicolon-separated values for supported lists. A name copied from a product title or a record that is not available in the target store cannot be assumed to resolve.
Check the definition’s reference type, then copy a supported identifier from the target store. Import referenced products or metaobjects first when needed, test one row, and verify that the preview names the intended existing product before importing the full file.
Import completed, but the existing product’s metafield did not changeThe matching product was not selected for overwrite
For product updates, Shopify matches the product by URL handle. If the import does not overwrite products with matching handles, matching rows can be ignored. A familiar title does not prove that the row identifies the existing product you intended to edit.
Start with a current export that retains URL handle and Title. Test a single known product, select overwrite only after the preview shows the exact expected update, and keep the untouched export until the change is confirmed.
Value became blank—or stayed unchangedA blank cell and an omitted CSV column send different instructions
When overwriting matching products, a blank non-required column can overwrite the corresponding existing value as blank. If that non-required column is absent from the import file, Shopify leaves the existing value in place. This distinction matters when a spreadsheet contains empty metafield cells for products you did not intend to edit.
For a targeted update, retain only the metafield columns you intend to manage and give every affected row an explicit value. Use a one-product test file first. If the preview is broader than expected, stop and rebuild from a fresh export rather than retrying the same file.
KNOW THE BOUNDARY
What can be checked before Shopify applies a metafield change?
Merch Preflight checks locally
- CSV rows, quoting, encoding, and recognizable headers
- Product handles and product-group consistency
- Common structural data dependencies
- Basic values such as numbers, prices, statuses, and inventory fields
Shopify and your store must check
- The metafield definition, owner, type, and validations
- Whether referenced products or metaobjects exist in the store
- Whether a handle matches the intended existing product
- The overwrite selection and final import preview
Your product names, custom data, SKUs, and supplier data stay in this browser.
FIVE-MINUTE TEST
Before you retry a Shopify metafield import
- 1Confirm the field owner
Use the product CSV only for product-level metafields.
- 2Check the definition
Verify the namespace, key, type, and validation rules in the target store.
- 3Export one target product
Preserve the metafield header, URL handle, and Title from the current store.
- 4Use one explicit test value
Match the type and use a supported identifier for any reference.
- 5Read the preview before overwrite
Confirm one expected product and metafield update before scaling up.
FAQ
Shopify CSV metafield import questions
What should a product metafield CSV header look like?
Shopify documents the identifier as product.metafields.<namespace>.<key>. A product export can also show the metafield name followed by that identifier in parentheses. Export the target store and preserve its exact header.
Why does the same CSV work in one Shopify store but not another?
Metafield definitions, namespaces, keys, validation rules, products, and reference records belong to the individual store. Start from the target store’s current export rather than a header copied from another store.
Can I use a CSV to update variant metafields?
Not through Shopify’s product CSV import/export workflow. Shopify directs variant metafield bulk edits to its variant bulk editor; verify the field owner before selecting your workflow.
Should I leave unrelated metafield cells blank?
Not in a broad overwrite file unless you intend to clear them. A blank included non-required column and an omitted column behave differently. Test one product and review the preview before applying the file.
Official references
This guide follows Shopify’s current documentation on product CSV files, metafield column headers, supported types, and overwriting matching products and metafield definitions and values. Shopify can change its templates and import behavior; its current export, definition settings, preview, and final import result remain the authority.