Shopify Custom Metafield Definitions: Import at Scale

A Shopify merchant spends an afternoon in the Shopify admin building out a complete custom metafield schema: eight definitions covering weight, resistance level, compatible models, warranty period, energy efficiency class, CE certification status, country of origin, and care instructions. Each definition is set to the correct type (number_decimal for weight, single_line_text_field for certification, json for compatible models) and saved. The schema looks right.

They export the supplier CSV, clean it up, and run it through Shopify's native product importer. The import completes without errors. Every product is in Shopify with correct titles, prices, and images.

Every custom metafield column is blank.

This is the gap at the centre of the shopify custom metafield definitions product import workflow. Creating a metafield definition in Shopify admin tells Shopify a field exists and what type it expects. It does not populate values. Shopify's native CSV importer cannot populate custom metafields: only the standard built-in product fields (title, vendor, price, SKU, barcode, images, tags, variants). The definitions wait, empty, until something fills them.

Why Shopify's Native Importer Cannot Populate Custom Metafields#

Shopify's standard product CSV format was designed around a fixed set of built-in product fields. The column names are specified by Shopify: Title, Body (HTML), Vendor, Type, Tags, Published, Option1 Name, Option1 Value, and so on. Custom metafield columns do not exist in this format.

Shopify does allow metafield population through the Admin API and through Matrixify-compatible CSV exports. But the standard product import path (the one most merchants reach through the Products > Import button) has no mechanism to read a column named custom.weight_kg and populate the corresponding metafield.

The result is that a merchant who builds a complete metafield schema and then imports products via the native importer ends up with two separate tasks: the import (which populates standard fields), and a manual metafield enrichment pass (which populates custom fields, typically via a third-party app or the API).

Importier's import wizard handles both operations in a single import run. The column mapping step reads columns from the supplier file and routes each value to its destination: a standard Shopify product field or a custom metafield. Weight data in a "Weight (kg)" column maps to custom.weight_kg and populates the metafield for every product in the batch.

Metafield Type Mapping: What Goes Where#

Shopify's custom metafield system supports multiple field types, and the type determines how the value is stored and validated. Matching the supplier column format to the correct metafield type is the first decision in the mapping configuration.

The most common metafield types and their import formats:

• number_decimal: stores a floating-point number. Supplier column value: 2.5 (not "2.5 kg"; units go in a separate field or in the metafield key name). Used for weight, dimensions, temperature ratings, fill volume.
• number_integer: stores a whole number. Used for warranty period in months, page yield, quantity per pack, minimum order quantity.
• single_line_text_field: stores a short text string. Used for certification status (CE, FCC, RoHS), country of origin, material type, care instruction summary. The most flexible type for short, structured text.
• multi_line_text_field: stores longer text with line breaks. Used for care instruction paragraphs, compliance notes, fit guide text.
• boolean: stores true/false. Used for binary attributes: recyclable (true/false), food-safe (true/false), outdoor-rated (true/false).
• json: stores a JSON object or array. Used for compatibility lists (compatible printer models), size tables (measurement data per size), and any structured data with multiple components.
• url: stores a URL. Used for product data sheet links, safety data sheet (SDS) URLs, manufacturer specification page URLs.

The column mapping step in Importier's import wizard identifies the destination metafield type from the definition and validates the column values before the import runs. A number_decimal field with a column value of "2.5 kg" returns a type mismatch in the preview; the merchant corrects the source data to "2.5" before pushing.

Namespace and Key Naming Conventions#

The metafield namespace and key combination must be set in Shopify admin before the import references it. A metafield identified as custom.weight_kg has namespace custom and key weight_kg. Most merchants default to the custom namespace for all their metafield definitions.

The problem with using custom as the only namespace for all metafields appears at scale. A store with 30 custom metafield definitions (covering dimensions, compliance, warranty, compatibility, care, and environmental attributes) stored entirely under custom becomes difficult to manage. custom.weight, custom.length, custom.height, custom.ce_marking, custom.rohs_compliant, custom.weee_registered, custom.warranty_months, custom.warranty_type, custom.compatible_models: the keys accumulate with no organisational structure.

A purpose-prefixed namespace approach groups related metafields under shared namespaces. Rather than custom.weight_kg, use dimensions.weight_kg. Rather than custom.ce_marking, use compliance.ce_marking. Rather than custom.compatible_models, use compatibility.models.

The practical benefits of purpose-prefixed namespaces:

• Shopify's admin interface groups metafields by namespace in the product edit panel. compliance. fields appear together, dimensions. fields appear together, without alphabetical interleaving of unrelated fields.
• Import column mapping in Importier can apply namespace-level defaults. A column mapping profile for electronics maps all compliance-related columns to the compliance. namespace.
• Theme developers querying metafields by namespace retrieve a logical group rather than scanning the entire custom. namespace for relevant keys.
• When a merchant adds a second category (for example, adding pet products to an electronics store), the dimensions.weight_kg metafield coexists cleanly with nutrition.calories_per_100g without key collisions.

According to Shopify's custom data documentation, the custom namespace is reserved for merchant-created metafields visible in the Shopify admin. Other namespaces (non-custom) are accessible via the Storefront API but not editable in the admin interface by default; plan the namespace structure before creating definitions, because changing a namespace means recreating the definition and re-populating all values.

1. 01
   Plan the metafield schema on paper before creating definitions in Shopify admin. Group related attributes into namespaces

   dimensions (weight_kg, length_cm, width_cm, height_cm), compliance (ce_marking, rohs_compliant, fcc_id, energy_class), warranty (period_months, type), compatibility (models, accessories). Name keys using snake_case with the unit suffix in the key name (weight_kg not weight)
2. 02
   Create each metafield definition in Shopify admin under Settings > Custom data > Products. Set the correct type for each key

   number_decimal for measurements, single_line_text_field for certification codes, boolean for binary compliance attributes, json for compatibility lists
3. 03
   Prepare the supplier file with one column per metafield value. Name the columns descriptively; the column name does not need to match the metafield key, because the column mapping step handles the translation
4. 04
   In the Importier import wizard, use the column mapping step to route each supplier column to its destination metafield key. The destination selector shows all defined metafield namespaces and keys; select the correct type-matched destination for each column
5. 05
   Review the import preview before pushing. The preview shows the first five products with all metafield values populated. Confirm the types match (no text in number fields), the JSON is valid for json-type fields, and boolean fields read true or false rather than Yes/No

Multi-Value Metafields and JSON at Import#

Some metafield types require structured input that a simple text value cannot provide. Compatibility lists and size tables are the two most common cases.

Compatibility lists store multiple values for a single metafield. A printer cartridge compatible with three printer models stores the list as a JSON array: ["HP LaserJet Pro M404", "HP LaserJet Enterprise M507", "HP LaserJet MFP M428"]. In the supplier CSV, this might appear as a comma-separated string in a single cell. The import wizard accepts comma-separated values for list-type metafields and converts them to the correct JSON array format before writing to Shopify.

Size tables store measurement data per size as a JSON object: {"XS":{"chest":78,"waist":60},"S":{"chest":82,"waist":64},"M":{"chest":86,"waist":68}}. If the supplier file has one column per measurement type (size_chest_cm, size_waist_cm, size_hip_cm) rather than a pre-formatted JSON column, the import treats each column as its own metafield, which works correctly if the metafield schema has separate keys for each measurement rather than a single JSON key for the full table. Both approaches are valid; the schema design determines which import configuration fits.

For articles that cover industry-specific custom metafield applications, the shopify fitness equipment import weight specs approach (separate numeric metafields per measurement) and the shopify size guide import for garment metafields approach (JSON table for the full size guide) each reflect different valid schema designs for different data shapes.

“A metafield schema designed with purpose-prefixed namespaces and type-matched keys takes one hour to plan. Rebuilding a flat custom-namespace schema after a year of catalogue growth takes considerably longer.

Validating Metafield Values Before Import#

The import preview in Importier shows the first five products with all mapped field values rendered, including custom metafield destinations. This is the validation point for the metafield data before it reaches Shopify.

Three common metafield validation failures caught at preview:

Type mismatch: a number_decimal destination receives a value like "2.5 kg" (text with a unit suffix). The preview flags this as a type error. Fix: strip the unit from the source column in the supplier file, or use a column mapping formula to extract the numeric portion.

Invalid JSON: a json metafield receives malformed JSON, typically a supplier compatibility list formatted as HP LaserJet Pro M404, HP LaserJet Enterprise M507 (a plain comma-separated string without brackets or quotes). The preview shows the value will fail the JSON type validation. Fix: either reformat the source column to valid JSON, or change the destination to a multi_line_text_field if the data does not need to be queried as structured JSON.

Out-of-range values: a number_integer destination receives a decimal value (for example, a warranty period of 1.5 instead of 18 months). The preview flags the precision mismatch. Fix: verify the unit interpretation in the source column.

According to Shopify's metafield types reference, each metafield type has a defined validation behaviour. The import preview surfaces these validations before the data reaches Shopify rather than after, avoiding a batch of products with silent metafield population failures.

Key Takeaways#

• Shopify's native CSV importer cannot populate custom metafields. Creating a metafield definition in admin tells the store the field exists; it does not populate values. The definition and the import population are two separate operations that Shopify's standard import does not combine.
• Metafield type must match the supplier column format before the import runs. A number_decimal field requires a numeric value with no unit suffix. A json field requires valid JSON. The import preview validates type matching before pushing.
• Purpose-prefixed namespaces (dimensions, compliance, compatibility, warranty) are more maintainable than a flat custom namespace. They group related fields in the admin panel, enable namespace-level import configuration, and prevent key collisions as the metafield schema grows.
• Multi-value metafields (compatibility lists, size tables) require attention to data format in the supplier file. A comma-separated string and a JSON array carry the same information but require different mapping configurations.
• The import column mapping profile saves the full metafield routing for re-use. Every future import from the same supplier applies the same column-to-metafield mapping without reconfiguration.

Set up your Shopify custom metafield definitions and populate them at import scale at importier.app.