Migrating Metafields and Custom Product Data to Shopify: A Practical Guide

If you’re moving to Shopify from WooCommerce, Magento, or BigCommerce, the products themselves usually migrate without much drama, titles, prices, images and descriptions map across reasonably cleanly. The custom stuff is where migrations go sideways. Size charts, material composition tables, care instructions, technical spec sheets, warranty terms, fit notes, the fields that make a product page actually useful, rarely have a direct equivalent in Shopify’s data model.

That’s because most other platforms store this information in a flexible, loosely-typed way (WooCommerce custom fields, Magento EAV attributes, BigCommerce custom fields), while Shopify uses a more structured system called metafields. The two aren’t the same shape, so a straight CSV export-and-import will either drop the data, dump it into one messy text blob, or silently fail on fields it doesn’t recognise.

This guide walks through what metafields actually are in Shopify, how they compare to what you’re likely working with now, how to plan a schema before you touch a single import, and the mapping approaches that actually hold up at scale. We’ll also cover validation and the pitfalls we see most often when this step gets rushed.

What Are Metafields in Shopify?

A metafield is a custom piece of structured data attached to a Shopify object, a product, variant, collection, customer, order, company, or the shop itself. Instead of stuffing extra information into the product description, metafields give that data its own defined field, type and validation rules, which means it can be displayed consistently, filtered, searched, and used in theme logic.

Every metafield is identified by three things:

Namespace, a grouping label, useful for keeping your custom data separate from data created by apps (for example, custom for your own fields, or an app’s reserved namespace like reviews).
Key, the specific field name within that namespace (for example, size_chart or material_composition).
Type, the data type Shopify enforces, such as single line text, multi-line text, number (integer or decimal), boolean, date, URL, file reference, JSON, rating, or measurement types like weight, dimension and volume. Shopify also supports list versions of most types, so a single metafield can hold multiple values (for example, a list of care instructions).

You define metafields in Settings > Custom data in the Shopify admin, where you create a “definition”, the reusable schema for that field, before populating actual values on individual products. Some definitions are Shopify’s own standard metafields (for things like garment fit, care guide, or nutritional information), which are worth using where they genuinely match your data, because themes and apps are more likely to recognise them out of the box. Everything else you define yourself as a custom metafield.

Metaobjects vs Metafields

It’s easy to conflate these, and the distinction matters for planning. A metafield attaches one piece of data to one object, a single product’s warranty length, for instance. A metaobject is a standalone, reusable content structure with its own fields, which you then reference from a metafield. A size chart is the classic example: instead of copying the same size chart text into a metafield on fifty different products, you build one size chart metaobject and reference it from a metafield on each relevant product. Change the metaobject once, and every product referencing it updates. If you’re migrating data that repeats across many products, size guides, ingredient panels, compliance certificates, plan for metaobjects, not duplicated metafields.

Common Source-Platform Equivalents

Knowing what you’re translating from makes the schema-planning step much faster.

WooCommerce: Custom Fields and ACF

WooCommerce stores extra product data as simple key/value pairs in wp_postmeta, often extended with Advanced Custom Fields (ACF) to add structure, field groups, repeaters, and basic types. The catch is that WooCommerce and ACF don’t enforce data types the way Shopify does. A “number” field in ACF might still contain stray text or inconsistent formatting because nothing stops it. Before migrating, expect to clean and standardise these values, because Shopify’s typed metafields will reject or mis-render anything that doesn’t match the type you’ve defined.

Magento: EAV Attributes

Magento’s Entity-Attribute-Value (EAV) model is conceptually closer to Shopify’s namespace/key structure than WooCommerce is, attributes belong to attribute sets and attribute groups, and each has a defined input type. This makes mapping more predictable, but Magento stores can have hundreds of attributes accumulated over years, many unused, duplicated, or set up as dropdown/select attributes with option values that don’t translate cleanly into Shopify’s type system. A metafield migration from Magento is as much an audit exercise as a technical one, see our Magento to Shopify migration guide for how this fits into a broader replatform.

BigCommerce: Custom Fields

BigCommerce’s native custom fields are plain key/value text pairs attached to a product, without the type enforcement or namespacing Shopify offers. If you’ve used BigCommerce’s product options or custom fields for things like spec sheets, you’ll generally have simpler mapping work than Magento, but you’ll be adding structure that didn’t exist before, which is a good opportunity to actually improve the schema rather than replicate a flat structure.

Planning a Metafield Schema Before You Migrate

The single most common cause of a messy metafield migration is skipping this step and going straight to import. A schema plan doesn’t need to be complicated, but it does need to exist before any data moves.

If you want a broader pre-migration checklist to work alongside this schema plan, our Shopify migration checklist covers the wider set of tasks beyond just product data.

A practical framework for planning your schema:

Audit the source data. Export every custom field, attribute, or ACF field currently in use, along with a sample of real values for each. Note which fields are actually populated versus legacy and empty.
Categorise each field. Sort into “maps to a Shopify standard metafield,” “needs a custom metafield,” and “should become a metaobject” (anything structured and reused across products, like size charts or spec tables).
Define your namespace convention. Decide early whether you’ll use custom for everything or split by function (for example, specs, care, compliance). Keep app-reserved namespaces in mind so you don’t create naming clashes with apps you plan to install later.
Choose types deliberately. Match Shopify’s type options to what the data actually is, don’t default everything to text just because the source platform did. A dimension should be a measurement type, not a string with “cm” typed after it.
Decide what’s customer-facing versus admin-only. Not every migrated field needs to appear on the storefront; some exist purely for internal reference or fulfilment.
Map each field to where it will render in the theme. A metafield with no theme placement is invisible to customers, even if the data imported perfectly.
Pilot on a small product subset first. Migrate and display 10-20 representative products before running the full catalogue through the same process, so mistakes get caught early rather than at scale.

Mapping and Import Approaches

Once the schema is set, there are three realistic ways to get the data in.

Shopify’s native metafield import/export. Shopify supports exporting and importing metafield values via CSV, with columns formatted as namespace.key. This works well for straightforward, already-clean data and smaller catalogues, but it expects your CSV to already match your defined types and structure, it won’t do any transformation for you.

Matrixify-type import apps. Bulk import/export apps built specifically for Shopify (Matrixify is the best-known) handle metafields, metaobjects, variants and images in a single pass, with more forgiving column matching and the ability to update existing products rather than only creating new ones. For most migrations of a few hundred to a few thousand products with moderately complex data, this is the sweet spot between control and effort.

Custom scripts via the Admin API. When source data needs real transformation, splitting a single Magento attribute into three Shopify metafields, converting EAV option IDs into readable values, or restructuring nested JSON specs into a metaobject, a script using Shopify’s GraphQL Admin API (with bulk operations for larger catalogues) gives you the control that CSV tools can’t. This is more development effort, and it’s exactly the kind of work where a migration going wrong quietly (data imported but malformed) is more damaging than one that fails loudly. If your source data is inconsistent, deeply nested, or spread across thousands of SKUs with real structural differences from Shopify’s model, this is the point where it’s worth involving specialists who do Shopify migrations regularly rather than debugging API bulk operations for the first time on a live catalogue.

Validating After Migration

Don’t treat the import as the finish line. Validation should cover:

Spot-checking a representative sample of products across categories, not just the first ten in alphabetical order.
Filtering by metafield in the admin to confirm values landed in the right field with the right type, rather than just “somewhere.”
Checking storefront rendering, since a metafield can be populated correctly and still not display if it hasn’t been added to the theme template.
Verifying metaobject references resolve correctly rather than showing blank or broken links.
Reviewing character and list-length limits, since Shopify enforces caps per type that some source platforms didn’t.
Confirming search and filtering still work if customers previously filtered by these attributes (for example, filtering by material or size).

Common Pitfalls

Losing structure by flattening data. Dumping a size chart or spec table into one long text metafield “to be safe” defeats the purpose, you lose the ability to filter, style, or reuse it.
Confusing metaobjects with metafields, leading to the same content duplicated across hundreds of products instead of centralised and referenced.
Assuming theme compatibility. Metafields only display if your theme is built for Online Store 2.0 and someone has added them to the relevant template or section, older or heavily customised themes may need developer work to surface the data at all.
Not reserving namespaces, which causes conflicts later when an app tries to create metafields with overlapping keys.
Skipping the pilot batch and discovering type mismatches only after the full catalogue has already imported.

Frequently Asked Questions

What’s the difference between a metafield and a metaobject in Shopify?
A metafield attaches one value to one object, like a single product’s warranty period. A metaobject is a reusable, structured content block, such as a size chart or ingredient panel, that multiple products can reference via a metafield, so you only maintain the content in one place.

Can I migrate metafields without a developer?
For straightforward data and smaller catalogues, Shopify’s native import tools or apps like Matrixify can handle it without custom code. Once you’re dealing with restructured or nested data, inconsistent legacy attributes, or metaobject relationships, developer involvement generally saves more time than it costs.

Will incorrect metafield migration affect my Shopify SEO?
It can, particularly if structured data like specifications or size information previously fed into rich snippets or on-page content that search engines indexed. Losing that structure during migration can weaken content depth on product pages, which is worth checking as part of a broader migration SEO review.

How long does a metafield migration typically take?
It depends heavily on catalogue size and how messy the source data is, but in our experience, schema planning and a properly mapped import for a mid-sized catalogue typically adds one to three weeks on top of the core product migration timeline, more if the source data needs significant cleanup first.

Do metafields transfer automatically when using a migration app?
Some migration apps will move basic custom fields automatically, but they rarely make good decisions about namespaces, types, or metaobjects on their own. Treat any automated transfer as a starting point that still needs schema review, not a finished result.

Ready to Get Your Custom Product Data Right the First Time?

Metafield planning is one of those steps that’s cheap to get right upfront and expensive to fix after launch. If you’re mid-way through scoping a platform move, it’s worth talking through your product data structure before the import starts. Book a call with our team and we’ll help you map out what actually needs to happen with your custom fields, size charts and spec data before migration day.