Cloning your Shopify store? Your reference metafields are about to go quietly null.

Why this happens

A product_reference, file_reference, or metaobject_reference metafield stores a Shopify GID — something like gid://shopify/Product/16001385332817. That number is specific to the store it was created in. Duplicate the store, migrate to a new one, or sync dev→prod, and every one of those IDs is gone; the destination store has never heard of 16001385332817. Shopify doesn't reject the import for this — the reference field is simply left empty, or the import quietly drops the row. Nothing in the success message tells you it happened.

The fix: resolve by handle, not by ID

A product's handle (its URL slug), a metaobject's type/handle pair, and a variant's parent handle + SKU are portable — they mean the same thing in every store, because the merchant chose them, not Shopify's database. Import a reference as a portable key instead of a raw GID, and re-resolution looks the destination store's own current objects up by that key at write time. The reference survives the move because it was never tied to the old store's numbers in the first place.

Proof, not a promise: the live before/after

We don't just say this works — we run it against a real Shopify store and show the actual result. The hardest version of this test isn't "import once," it's the reference surviving a change on the other end: what happens if the thing you're pointing at gets deleted and recreated under the same handle — the exact shape of a real "we cloned the store, then kept building" scenario? We only own one live dev store, so this is simulated by deleting the target product after the first fire, then recreating it under the same handle, then firing the identical import row again unchanged.

The one type this doesn't fix: file references

A file_reference metafield (a spec-sheet PDF, a size-chart image) points at a Shopify GenericFile or MediaImage object — and unlike products or metaobjects, files have no merchant-chosen handle to re-resolve by. We do not pretend otherwise: a file reference is honestly ledgered as unresolved rather than guessed at or silently dropped. In the same live run above, rel_file is reported absent from the owner's metafields after every fire — never written, never faked. If you need file references to survive a store move today, re-upload the file to the destination store and reattach it manually; we'll tell you exactly which rows need that, we just won't pretend to have done it for you.

What the free download is — and isn't

The demo file below shows the portable-key format described above: product_reference and metaobject_reference columns written as handles instead of raw IDs, and a file_reference column left as an honest gap with a note on what to do about it. It's a format reference you can copy from — opening or re-uploading this file does not connect to or write to any Shopify store. The actual cross-store resolution shown above (looking up a handle against a live destination store and writing the resolved GID) requires a connected store, which is what the full Importable app does. This page and the free download are honest about that line: format guidance is free and stateless; live resolution needs a connection.

Want this reference format loaded straight from your own store? Install xlsx-for-ai and ask Claude or Cursor to check your metafield export for raw IDs that won't survive a store move.

Download the demo file

metafields-store-move-references.xlsx — a small catalog showing all three reference types (product_reference, file_reference, metaobject_reference) in the correct portable-key format, with an inline read-me row explaining each column.