Docs › How-to guides

Import references

A reference field points at something else in your store — a product, a file, a page, another metaobject entry. Getting a reference into a spreadsheet cell is the fiddliest part of any import, so this page collects everything about it in one place.

Two different things called “reference”

Don't confuse them; the rules are different.

The owner reference — which resource am I setting a value on?

The owner_reference column in a metafield values import. Accepts handles, IDs, GIDs or SKUs depending on the owner type. Covered below →

A reference value — what is this field pointing at?

The value of a product_reference, file_reference, metaobject_reference field or one of their list.* variants. Nearly always a GID, with metaobjects as the friendly exception. Covered below →

Owner references

What owner_reference accepts depends on the owner type:

Handle lookups exist only where Shopify documents a query that accepts one. It has no such lookup for pages, articles or blogs, so ImportKit rejects a handle up front with a message telling you to use the ID, rather than guessing at something that might resolve to the wrong resource.

Finding numeric IDs

Open the resource in the Shopify admin and read the URL. The last number in /admin/pages/123456789 is the page's ID. Same shape for articles, blogs, products and collections.

For more than a handful, query the Admin API for handles and IDs and join that against your file in a spreadsheet.

The GID form

A GID is Shopify's global identifier: gid://shopify/Product/8123456789. It's the most explicit thing you can put in a cell, and it never needs a lookup.

ImportKit checks that a GID's resource type matches the row's owner_type before writing anything:

owner_reference "gid://shopify/Customer/1" is not a PRODUCT

That's the guard that stops a mis-sorted spreadsheet writing metafields onto the wrong resources.

SKU lookups

sku:LIN-SHIRT-M is convenient for variants, but Shopify doesn't enforce SKU uniqueness. If two variants share a SKU:

More than one product variant has SKU "LIN-SHIRT-M" — use its ID or gid instead

An error rather than a guess, because the wrong variant is worse than no variant.

Reference values

When the value of a field is a reference, use a full GID — with one friendly exception.

Metaobject references are the forgiving ones

Because ImportKit can read your metaobject entries, it resolves them by name. In a blog article import a metaobject reference column will match on:

• the entry's handle — jane-doe
• its display name — Jane Doe
• any of its field values — an email stored on the entry, for instance

Matching is case-insensitive, so JANE DOE works too. In metaobject entry imports, reference fields resolve by handle or GID.

This is what makes references practical from a spreadsheet: your source data almost certainly has “Jane Doe” in it, and almost certainly doesn't have a Shopify GID.

File references need the file to exist

ImportKit doesn't upload files. A file_reference has to point at something already in Content → Files. Upload the images first, then reference them.

The exception is a blog article's featured image, which takes a public image_url that Shopify fetches and hosts itself.

Reference lists

A list.product_reference field holds several references in one cell. Two things to know, and the second is a genuine sharp edge.

Separators

Comma-separated, newline-separated within the cell, or a JSON array. If the cell contains any line break, newlines become the separator and commas are kept inside items.

gid://shopify/Product/1, gid://shopify/Product/2
["gid://shopify/Product/1","gid://shopify/Product/2"]

Bare IDs only work for products

Article reference lists are comma-only

One more exception: in blog article imports, metaobject reference lists are comma-separated only. A newline-separated cell won't resolve there.

When a reference doesn't resolve

For metaobject references in article imports, an unresolved value is a warning, not a failure. The article is still created — without that reference — and the row carries:

custom.written_by: no metaobject entry matches "Jane Do", so it was left out

This is the case people miss, because the counts all look fine. After any import involving references, read the warnings in the job results, not just the success total.

The 250-entry lookup limit

Resolving a metaobject reference by handle or name searches the first 250 entries of the referenced type, and that read isn't paginated. If you have more than 250 entries of a type, references to entries beyond the first 250 won't resolve by name.

The fix is straightforward: use full gid://shopify/Metaobject/… values, which need no lookup at all. Get them by exporting your entries from the Admin API, or from the ID column of the ImportKit job that created them — every successful row records the ID of what it created.

Collision detection — the part that decides create versus update for entries — is fully paginated, so this limit only affects reference resolution. All limits →

Import in dependency order

References resolve at the moment the row is processed, so the target must already exist.

1. Metaobject definitions — so metaobject_reference<author> can be narrowed to a type.
2. Metaobject entries — the things that will be referenced.
3. Files — uploaded in the Shopify admin.
4. Everything that references them — metafield values, article rows, entries of other types.

Within a single file, rows are processed top to bottom, so a row referencing an entry created by an earlier row in the same import works. Across import types, order the imports. Full ordering guide →

Narrowing a metaobject reference field

When creating the definition, use Shopify's shorthand so the field only accepts one type of entry:

name,key,type,ownerType
Written by,written_by,metaobject_reference<author>,ARTICLE
Related recipes,recipes,list.metaobject_reference<recipe>,PRODUCT

ImportKit resolves author to that definition's ID and stores it as a validation. If the definition doesn't exist yet the row still imports, with a warning that the field will accept any metaobject rather than only authors — which is usually not what you wanted, so import definitions in order.

Reference checklist

• Owner references use handles where the owner type allows them, IDs for pages, articles and blogs.
• No IDs copied from a different store — they mean nothing in this one.
• Reference values use full GIDs, except metaobject references where handles are fine.
• Reference lists use GIDs, unless the type is list.product_reference.
• Referenced metaobject entries and files already exist.
• Fewer than 250 entries of a type, or you're using GIDs.
• You've read the warnings in the job results after importing.

Next