All import types
Five content types, one wizard. They behave the same way in most respects, and this page is about the places where they differ.
Which one do I need?
- I want to create new fields on products, articles, collections…
- Metafield definitions
- I have a spreadsheet of values to put into fields that already exist
- Metafield values
- I want a new kind of custom content: authors, size charts, FAQs, locations
- Metaobject definitions first, then metaobject entries to load them
- I have a list of things to load into a metaobject I already defined
- Metaobject entries
- I'm moving a blog into Shopify
- Blog articles
If “definition” versus “value” isn't a distinction you've had to make before, two paragraphs on it here will save you time.
Side by side
| Type | Needs a target? | Pre-import check | Fixed columns? | Template | Re-running the same file |
|---|---|---|---|---|---|
| Metafield definitions | No | Yes | Yes | Yes | Matched to existing: skip, update or fail |
| Metafield values | No | Yes | Yes | Yes | Matched to existing: skip, update or fail |
| Metaobject definitions | No | Yes | Yes | Yes | Matched to existing: skip, update or fail |
| Metaobject entries | Yes (which definition) | Yes | No, columns come from the definition | Yes | Matched by handle: skip, update or fail |
| Blog articles | Yes (which blog) | No | Yes, plus article metafields | Yes | Creates duplicates |
Reading that table
- Needs a target
- An extra choice on the upload step, above the drop zone. For metaobject entries the target isn't cosmetic: the columns you can map are generated from the definition you pick, so changing it changes the mapping step.
- Pre-import check
- Four types are uniquely keyed, so ImportKit can compare your file against your store and predict the outcome of every row for free. Blog articles aren't keyed by anything, so there's nothing to compare against and no check step. More →
- Template
- Every type has a Download template button on the upload step. The metafield and metaobject definition templates have one worked example row per common setup, plus a separate column guide CSV. The other types get a header row plus one example row.
- Re-running the same file
- This is the important column. For four types, a second run is safe and controlled by your conflict mode. For blog articles it duplicates the articles, because articles are never matched: every row creates a new article.
What makes a row a “duplicate”
Each type has its own notion of identity. It's worth knowing, because it decides when a row is a create and when it's an update.
| Type | A row is identified by |
|---|---|
| Metafield definitions | ownerType + namespace + key |
| Metafield values | owner_type + owner_reference + namespace + key |
| Metaobject definitions | type |
| Metaobject entries | handle, within the target definition |
| Blog articles | nothing: every row is a new article |
For metafield definitions, metaobject definitions and metaobject entries, two
rows in the same file with the same identity are caught too: the second is
reported as duplicate of row N rather than quietly colliding
mid-import. Metafield values and blog articles don't have this in-file check.
The order to import in
If you're setting up custom data from scratch, or copying a store, dependencies run in one direction. Following it means every reference resolves on the first attempt.
-
Metaobject definitions
Nothing depends on anything else. Do these first so metafield definitions can point at them.
-
Metafield definitions
A
metaobject_reference<author>type needs theauthordefinition to exist already. It'll still import without it, but with a warning that the field will accept any metaobject rather than only authors. -
Metaobject entries
Needs its definition. Also creates the entries that later references point at.
-
Metafield values, and blog articles
Last, because these are the rows that reference everything else: definitions for their types, metaobject entries for their reference values, and products or pages as their owners.
A full worked migration in this order →
What's the same for all five
- Your column names don't have to match anything. Matching headings are mapped for you, and you pick the rest.
- Values are trimmed.
- Ignored and unmapped columns are never sent to Shopify.
- One credit per row written; skips, conflicts and errors cost nothing.
- Rows are processed in parallel, automatically slowed to stay within Shopify's rate limits.
- Every row gets a durable outcome you can read afterwards in Jobs.
- Cancel stops between rows; for a cancelled or failed job, Retry continues from the first row not yet attempted.
- Nothing is ever deleted, and no import can be rolled back.