How to migrate metafields between Shopify stores
Metafields Guru can copy metafields and metaobject fields from one Shopify store to another - for example, from a development or staging store to production, or from an existing store to a new one. Plain values (text, numbers, JSON, etc.) can be moved with a regular export and import. Reference metafields need the Migration export mode, described on this page.
Why reference metafields can't be copied as is
Shopify stores the value of a reference metafield (product_reference, metaobject_reference, file_reference, etc.) as a GID - a system ID such as gid://shopify/Product/8123456789. GIDs are assigned by Shopify and are unique to each store: the "same" product in two different stores always has two different GIDs. If you export a reference metafield with its GID and import it into another store, the GID will point to a resource that doesn't exist there.
What can be the same in both stores are secondary identifiers - product handles, variant SKUs, customer emails, and so on. The Migration mode relies on them.
How the Migration mode works
When you export data in the Migration mode, Metafields Guru replaces every GID in reference metafields with a secondary identifier of the referenced resource. When you import that file into another store, the app looks up each identifier in that store and converts it back to the GID that is valid there.
| Metafield type | Exported as | Example |
|---|---|---|
product_reference | product handle | blue-cotton-t-shirt |
variant_reference | variant SKU | TS-BLUE-M |
collection_reference | collection handle | summer-sale |
page_reference | page handle | size-guide |
article_reference | article handle | how-to-wash-cotton |
metaobject_reference, mixed_reference | metaobject type and handle | designer/jane-doe |
customer_reference | customer email | jane@example.com |
company_reference | company name | Acme Corp |
order_reference | order name | #1001 |
file_reference | file URL | https://cdn.shopify.com/s/files/…/photo.jpg |
List types (list.product_reference, list.metaobject_reference, etc.) are converted item by item, so a list of three product GIDs becomes a list of three handles:
Default: ["gid://shopify/Product/8123456789","gid://shopify/Product/8123456790"]
Migration: blue-cotton-t-shirt, red-cotton-t-shirt
Only reference metafields are affected - all other values are exported exactly as they are stored. The source store is never changed: an export only reads data.
Step-by-step migration
1. Prepare the target store
The import can only link a metafield to a resource that already exists in the target store and has the same identifier. Before importing:
- Create the referenced resources - products, variants, collections, pages, blog articles, customers, companies - with the same handles, SKUs, emails, or names as in the source store.
- Create the metafield definitions. They are required for
metaobject_referencemetafields and recommended for all others. If you manage your definitions with metafield sets, you can export the sets from the source store and import them into the target store. - Migrate metaobject entries first. If your metafields point to metaobjects, export the metaobjects from the source store in the Migration mode and import them into the target store before importing the metafields that reference them. Metaobject fields can reference other resources too, and they are converted the same way.
Files are an exception: they don't need to exist in the target store in advance (see how references are resolved below).
2. Export the data in the Migration mode
In the source store, open Bulk Actions → Export, select the resource type, filters, and metafields as described in the export guide, and set Export mode to Migration. Both the "rows" and "columns" file formats are supported.
3. Import the file into the target store
Install Metafields Guru in the target store, open Bulk Actions → Import, and upload the CSV file as described in the import guide. Use a secondary identifier (handle, SKU, email) as the resource identifier - the GIDs of the metafield owners from the source store don't exist in the target store either.
To resolve references, the app needs read access to every referenced resource type in the target store (products, metaobjects, files, customers, orders, etc.). If any of those permissions are missing, the import screen shows a warning with a link to grant them. Rows that need a missing permission fail with an error that names the required access scope.
4. Check the results
When the import is finished, open the History tab of the Bulk Actions menu and download the results. Every row that could not be imported is listed with the reason, for example Product with handle "blue-cotton-t-shirt" not found.
How references are resolved on import
- Handles, SKUs, emails, and names are looked up in the target store and replaced with the matching GIDs. Product, collection, page, and article handles are normalized the same way Shopify generates handles, so letter case doesn't matter.
- Metaobjects are looked up by type and handle (
designer/jane-doe). For ametaobject_referencemetafield with a definition in the target store, the type can be omitted - a plain handle such asjane-doeis enough, because the type is taken from the definition.mixed_referencevalues always need thetype/handleform. - Files are downloaded from the URL and uploaded to the Files section of the target store, and the new file is used as the reference. If the same file has already been uploaded, the existing file is reused instead of creating a duplicate. The URL must be publicly accessible during the import (the Shopify CDN URLs produced by the export are).
- GIDs are left unchanged. A file can mix GIDs and identifiers, so you can still use it to update the original store.
Limitations and troubleshooting
- A resource without an identifier keeps its GID. If a referenced variant has no SKU, a customer has no email, or a metaobject type or handle is missing, the export writes the original GID instead. Such a value will fail in the target store. Fill in the identifier in the source store and export again, or replace the value in the CSV file manually.
- Identifiers should be unique. Handles are always unique in Shopify, but SKUs, company names, and order names are not. Make sure the identifiers used in your references are unique in the target store, so that each reference points to the intended resource.
- Orders rarely migrate. Order names (
#1001) are assigned by each store independently, so anorder_referencewill only resolve if an order with the same name exists in the target store. - The Readable mode is not for migration. Readable values (product titles, display names) are meant for people, not for import. Use the Migration mode for any file you plan to import into another store.
FAQ
Can I copy metafields from a development store to a live store?
Yes. Export the data from the development store in the Migration mode and import the file into the live store. Reference metafields will point to the matching products, collections, metaobjects, and files in the live store, provided they have the same handles (or SKUs, emails, etc.).
Does the Migration mode change anything in the source store?
No. An export only reads data - the identifiers are written to the CSV file, not to the store.
Can I edit the migration file in a spreadsheet before importing it?
Yes. Handles and SKUs are easier to read and edit than GIDs, so the Migration mode is also convenient for bulk-editing reference metafields in a spreadsheet and importing them back into the same store.
Do I have to migrate files manually?
No. Files referenced by file_reference metafields are uploaded to the target store automatically during the import.