Shopify Metafield CSV Format: Namespace, Key, and Types
Understand Shopify product metafield CSV headers, namespace/key rules, supported CSV types, lists, and value limits.
Shopify product metafields do not use a fixed set of columns. Each metafield becomes a dynamic product CSV header whose namespace and key identify the definition.
The product metafield header format
The canonical form is product.metafields.<namespace>.<key>. Shopify exports can also include a readable name before the identifier, such as Fabric (product.metafields.shopify.fabric). For a prepared import, the bare canonical header is enough and avoids ambiguity.
Namespace and key allow letters, numbers, hyphens, and underscores. The namespace is 2–255 characters and the key is 2–64 characters. Nablyx asks for the compact namespace.key form and generates the full CSV header.
Match the existing definition type
Shopify's product CSV supports common scalar types such as boolean, color, date, date/time, dimensions, money, decimal and integer numbers, product references, text, URLs, volume, and weight. It also supports list variants for several of those types. The type is not encoded in the header, so the existing Shopify definition remains the source of truth.
Lists use semicolon-separated items
Supported metafield lists are represented as semicolon-separated values in a CSV cell. Most list types allow up to 128 items; metaobject-reference lists have a higher documented item ceiling. Individual values still need to fit the documented size and format for their type.
Validate what a standalone CSV can actually prove
A browser-only preparer can validate the public schema: identifier syntax, supported types, standard value formats, sizes, and list counts. It cannot know a store's custom definition validation without connecting to that store. Use the preflight as a structural check, then let Shopify remain authoritative for definition-specific rules.
Check your Shopify metafield CSV formatSee the transformation
Awkward source headers become import-ready columns.
Rename the columns you need while keeping every value under the correct header.
cust_idcustomer_idgiven_namefirst_namemailemail✓ Values stay with the right column
Need to do this now?
Check your Shopify metafield CSV formatRelated tools
Open the tool this guide is about, or explore a related one.
- CSV column mapper and renamerRename, reorder, and remove CSV columns before importing data into a CRM, store, database, or accounting system — without uploading your file.
- Validate CSV files online freeScan a CSV once for structural, encoding, header, delimiter, and whitespace problems without changing the file.
- Clean and fix CSV files — no uploadRepair common CSV problems including wrong delimiters, uneven rows, empty lines, whitespace, BOM markers, and duplicate headers.