Docs › How-to guides

Copy custom data to another store

Development store to production, agency template to a new client, one region's store to another. The custom data layer doesn't come along with a theme. There's no dedicated migration tool: you build CSVs from the source store and run them through the normal import wizard in the destination, one type at a time.

The order that works

Dependencies run one way. Follow this sequence and every reference resolves on the first attempt.

1. Products and pages in place

   The destination needs the resources you'll be attaching values to. Product imports in ImportKit are coming very soon. In the meantime, get the catalogue there the way you normally would. Keep the handles identical between stores: that's what makes step 5 trivial.

2. Metaobject definitions

   Nothing depends on anything else, and metafield definitions may need to point at them. Guide →

3. Metafield definitions

   Now the metaobject_reference<author> shorthand resolves, because the author definition exists. Guide →

4. Metaobject entries

   The actual authors, locations, size charts. If entries of one type reference entries of another, import the referenced type first. Guide →

5. Metafield values

   Last, because these reference everything else: definitions for their types, entries for their reference values, products as their owners. Guide →

6. Blog articles

   Also last, and with care: articles are never matched, so every run creates new articles. Run this one exactly once. Guide →

Building the files

ImportKit imports; it doesn't export from a source store. You'll be assembling the CSVs yourself, and there are three practical routes.

From a downloaded template

For definitions, this is usually fastest. Open the source store's Settings → Custom data, download ImportKit's template in the destination store, and transcribe. A store with 20 definitions takes about fifteen minutes and gets you an artefact you can reuse on the next store.

From a Shopify product export

For metafield values, export products from the source store (Products → Export) and use the Handle column as your owner_reference. Shopify's product export includes metafield columns for definitions that exist, which gives you the values themselves too. Reshape them into one row per value.

From the Admin API

If you're technical, querying metafieldDefinitions and metaobjects on the source store and writing out ImportKit's columns is straightforward, and gives you a repeatable script. The column names are documented on each import type's page.

Handles are the hinge

Metafield values identify their owner by reference, and the cleanest reference is a handle. If product handles match between the two stores, your values file works unchanged. If they don't, you'll need a mapping column translating old handle to new. That's real work, so it's worth preserving handles during the product migration.

Same principle for metaobject entries: keep entry handles identical and any metafield value referencing them resolves without editing.

IDs, by contrast, never transfer. A gid://shopify/Product/8123456789 from the source store means nothing in the destination. Anywhere your source data uses IDs, convert to handles before importing. This is the single most common migration mistake.

The pages, articles and blogs exception

Those three owner types accept numeric IDs or GIDs only. ImportKit can't look them up by handle. So metafield values on pages and articles can't be moved by handle, and you'll need the destination store's IDs.

Get them from the admin URL: the number in /admin/pages/123456789 is the page ID. For a handful of pages that's fine; for hundreds, query the Admin API for page handles and IDs and join against your file.

Rehearse on a development store

Because imports can't be undone, the whole sequence is worth running once somewhere disposable. A Shopify development store is the place for it, and a Starter Pack is usually enough for a rehearsal.

1. Install ImportKit on a fresh development store.
2. Buy a Starter Pack and run all six steps in order.
3. Check the results in the admin, and read the warnings, not just the counts.
4. Fix the files.
5. Run the same files against production.

You end up with a set of CSVs you know work, which is a much better position than discovering a bad owner type on row 340 of a live import.

Which conflict mode

Use Skip for the whole migration. It's the default, and its worst case is that nothing happens. If the destination already has some definitions, Skip adds what's missing and leaves the rest alone, for free, since skipped rows aren't charged.

Consider Fail if the destination should be genuinely empty and you want to be told if it isn't. A clean run in Fail mode is an assertion that nothing already existed.

Avoid Update on a first migration. You'd be overwriting whatever is there with no record of what it was. Conflict modes →

Verify before moving on

Check each step in the destination admin before starting the next:

Also read the job's row results. A row can succeed while quietly dropping a reference it couldn't resolve. That shows up as a warning, not a failure.

One thing to check afterwards

A definition's storefrontAccess decides whether your theme can read the field. If you copied definitions and your theme suddenly can't find them, check that PUBLIC_READ came across. It's easy to leave blank in a hand-built file, and the symptom looks like missing data rather than a permissions setting.

Migration checklist

• Products and pages exist in the destination, with the same handles.
• Files are built in dependency order: metaobject definitions → metafield definitions → entries → values → articles.
• No source-store IDs anywhere in the files: handles instead, except for pages, articles and blogs.
• Conflict mode is Skip (or Fail, deliberately).
• The whole sequence has been rehearsed on a development store.
• The pre-import check is clean, or its remaining errors are understood.
• Your balance covers the total across all the imports.
• The article import is planned to run exactly once.
• Storefront access is set on any definition the theme needs.

Next