How to Import Shopify Product Metafields with a CSV

A Shopify product CSV can update normal product fields and product metafields in the same import. The reliable workflow is to start from product rows you can identify, map only the attributes you intend to update, and validate the metafield columns before Shopify sees the file.

Start with product identity columns

For product updates, keep the product identity fields Shopify expects in the CSV, especially Title and URL handle (older compatible files can use Handle). If your source comes from an ERP or supplier, map those fields first. Keep the values stable so an attribute update does not accidentally target the wrong product.

The browser-local source limit in Nablyx is 200 MB. The source rows and generated CSV stay on your device.

Map each attribute to a metafield

A product metafield column uses product.metafields.<namespace>.<key>. For example, an ERP column named Material might become product.metafields.custom.material. Choose the metafield type that matches the definition already created in Shopify; the type is used for local validation and is not written into the CSV header.

Validate the complete file before export

The preflight checks namespace/key syntax, duplicate target headers, row shape, documented value formats and ranges, value-size limits, and list item limits. Empty metafield cells are left unchanged by the preparer; Shopify decides their import meaning from the import/update context.

Import only after definitions exist

The CSV does not create metafield definitions. Create or confirm each product metafield in Shopify first, with the same namespace, key, and type you selected during preparation. Then download the prepared CSV and run the normal Shopify product import. Store-specific rules such as custom choices, regular expressions, or merchant-defined min/max validation still need to be checked in Shopify.

Prepare your Shopify metafield CSV

See the transformation

Awkward source headers become import-ready columns.

Rename the columns you need while keeping every value under the correct header.

cust_idcustomer_id

given_namefirst_name

mailemail

✓ Values stay with the right column