Data Mapping for Shopify Platform Migrations

The most expensive hour of a migration

A brand we audited last year lost three months of lifecycle performance because of one mapping decision made in an afternoon. The previous vendor dumped every WooCommerce custom field into the Shopify product description as HTML. It looked fine on the PDP. The problem showed up later. Klaviyo flows referencing ingredient data could not find ingredient data. The filter on the collection page could not filter. Ads that ran against product feeds crashed because structured fields were not structured.

Ninety minutes of attribute mapping at the start would have saved eighty days of cleanup. This is the post about those ninety minutes.

▸ Audit source fields before exporting. Half are dead weight. ▸ Pick the destination shape deliberately: native, metafield, or metaobject. ▸ Validate row counts and key-field diffs before cutover. ▸ Never flatten structured data into rich text. Ever.

Why data mapping is the spine of a migration

A migration has three layers. Platform, presentation, and data. Platform is the easy part. Shopify admin works, the Storefront API is documented, theming is mature. Presentation is the visible part. The theme rebuild is what stakeholders watch. Data is the invisible part that determines whether your store works five years from now.

Data decisions compound. The metafield namespace you pick at week two is still in your codebase at year four. The metaobject you did not create becomes three apps you did not need. The customer tag taxonomy you skipped becomes a Klaviyo segmentation gap that never fully heals.

For the operational side of migration see our platform migration service and leaf pages like WooCommerce to Shopify and Magento to Shopify.

Step one. Inventory the source.

Before touching Shopify, take stock of what you have. Pull a full list of every custom field, attribute, taxonomy, tag, and metadata layer on the source platform. For each one record four things.

▸ The field name and type. ▸ How many records actually use it. ▸ Whether it drives behavior anywhere. Merchandising, search, ads, email, reviews. ▸ Whether anyone edits it regularly.

This audit kills a surprising amount of work. A typical Magento store has two hundred attributes and uses eighty. A typical WooCommerce store has sixty meta keys and uses twenty. The dead ones do not come across. They get documented and archived for the record.

Step two. Choose destination shapes.

Shopify gives you five places to put data.

▸ Native product or variant fields. Title, SKU, price, weight, options. ▸ Metafields on products, variants, customers, orders, or collections. ▸ Metaobjects, which are structured entities that products reference. ▸ Tags, which are flat string labels. ▸ Custom app tables, for the rare case where none of the above fit.

The choice per field is the mapping decision. Here is the rule we use.

Tags feel tempting because they are easy. They are also the trap. Tags have no type, no namespace, and no validation. A misspelled tag on one product is invisible. Use them for flat flags and nothing else.

Step three. Namespace metafields properly.

Shopify metafields live in a namespace plus key structure. Namespaces exist to prevent collisions between apps and teams. Use them.

Our standard scheme has three groups. One namespace for catalog data the team edits. One namespace for app-owned data that must not be touched. One namespace for computed or synced values from external systems. A fourth namespace sometimes exists for brand-specific structured content if it does not belong in a metaobject.

The practical value shows up in year two. When an app shows up and wants to write to the store, its metafields live in its namespace and your catalog metafields are safe. When you retire an app, its namespace goes with it and you do not have to audit every product.

Step four. Model metaobjects for structured content.

Metaobjects are the feature that most first-time Shopify migrators underuse. A metaobject is a structured entity with its own fields, editable in its own admin screen, referenced from products or pages or other metaobjects.

Good candidates for metaobjects.

▸ Ingredient lists with supplier, purpose, and sourcing notes. ▸ Sizing charts with measurement grids. ▸ Certifications with logos, dates, and descriptions. ▸ Recipes, tutorials, or usage guides. ▸ Authors or founders referenced across articles.

Products reference the metaobject. Edits happen once. Display logic on the storefront reads through the reference. This is how you avoid the "changed the ingredient on forty products" cleanup operation.

Step five. Map customer data carefully.

Customers are the second-most-important data object after products. Map them like it matters.

Email, name, accepts-marketing flag, and address book migrate natively. Order history migrates as closed orders attached to the customer. Tags and metafields handle the rest. Common customer metafields we set up at migration.

▸ Acquisition source, if tracked upstream. ▸ First-order date. ▸ Loyalty tier, if any. ▸ Subscriber status for each product line. ▸ VIP flag for customer service prioritization.

Do not migrate passwords. You cannot. Send the account invite email at cutover. See the migration redirect plan for how to sequence the invite against the redirect cutover so it does not collide with campaign sends.

Step six. Order history as closed orders.

Orders migrate in closed state with line items, totals, taxes, and shipping lines. Fulfillment, refund, and return history attach as notes or structured metafields depending on what the brand uses them for. Do not try to migrate in-flight orders. Freeze fulfillment, migrate static history, and start the new platform with a clean state.

For D2C brands with heavy return workflows we export the full order archive to a data warehouse at the same time. That gives finance and analytics a platform-independent history regardless of what Shopify retains at scale.

Step seven. Validate before cutover.

Row counts first. Source count equals destination count for every object type. If not, find the missing rows.

Key-field diffs second. Pick five to ten fields per object that must match. Price, inventory, SKU, weight, title. Run a diff report. Any discrepancy is a bug.

Spot checks third. The extreme rows. The longest-SKU product. The product with the most variants. The customer with the most orders. The oldest order. If the extremes work, the middle usually works. If an extreme fails, there is a pattern to find.

Business logic fourth. Does a test cart add correctly? Does a test subscription charge? Does a Klaviyo flow fire? Does a review app display the right count? Each of these is a five-minute check that saves a ten-hour firefight.

Step eight. The handoff document.

The document matters as much as the data. Write down every mapping decision. Why this field became a metafield rather than a tag. Why this metaobject exists. Which namespaces are app-owned and which are team-owned. Which source fields did not come across and why.

This is the document your team reads in a year when someone asks "can we filter collections by ingredient origin". The answer is in the metaobject design. The document tells them where to look.

What to do this week

▸ Pull a full custom-field and attribute inventory from your source platform. ▸ Mark each field as keep, retire, or migrate-with-transform. ▸ Draft a metafield namespace scheme and share it with every app owner. ▸ List three candidates for metaobjects from your current catalog and sketch their fields. ▸ Book the validation pass as a separate tracked task before cutover.

Related reading

For companion operational guides see the Shopify migration redirect plan and Shopify technical SEO audit. For the service context see platform migration, Shopify development, and headless development. For platform comparisons see Shopify vs WooCommerce and Shopify vs BigCommerce.

FAQs