Docs › What you can import › Metafield values

Metafield values

One row sets one metafield value on one resource that already exists. This is the import that fills in the fields — care guides on products, reading times on articles, a motto on the shop itself.

A worked example

owner_type,owner_reference,namespace,key,value
PRODUCT,merino-crew-neck,custom,care_guide,"Hand wash cold. Lay flat to dry."
PRODUCT,linen-shirt,custom,highlights,"Breathable, Pre-washed, Recycled buttons"
PRODUCTVARIANT,sku:LIN-SHIRT-M,custom,fit_note,Runs slightly large
SHOP,,custom,store_motto,Built to last

Four values on four different kinds of owner: two products by handle, a variant by SKU, and the shop itself. Four rows, four credits.

Note there's no type column. That's fine as long as a metafield definition already exists for each owner type, namespace and key — see the type column.

Columns

These columns use snake_case, unlike the definition importers. The template and column guide will always tell you the current names.

The type column, and when you need it

Shopify needs to know a metafield's type. If a definition already exists for that owner type, namespace and key, ImportKit reads the type from it and you can leave the column out entirely. If no definition exists, Shopify has nothing to infer from and the row fails with:

No metafield definition exists yet for PRODUCT custom.store_motto,
and no type column was given.

Two ways to fix it, and the first is usually better:

1. Import the definition first using metafield definitions. You get a proper field with a name, a description, validations and a pin in the admin.
2. Add a type column to your values file. The metafield gets created without a definition — it works, and your theme can read it, but it won't appear as a labelled field in the admin editor.

Owner types

You can set metafield values on these seven owner types:

The owner type dropdown on the mapping step lists only the owner types your store's granted permissions cover, so you'll see this constraint before you build a file around it. Full permissions reference →

Referencing the owner

What you can put in owner_reference depends on the owner type, and the differences aren't arbitrary — handle lookups exist only where Shopify provides a query that accepts one.

Why pages, articles and blogs need IDs

Shopify's Admin API has no documented lookup that turns a page, article or blog handle into an ID. Rather than guessing, ImportKit rejects a handle up front with a message telling you to use the numeric ID. You can get IDs from the URL in the Shopify admin: the last number in /admin/pages/123456789 is the page's ID.

SKU lookups

sku: is convenient, but SKUs aren't guaranteed unique in Shopify. If two variants share one you'll get:

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

Deliberately an error rather than a guess, since the wrong variant is worse than no variant.

A GID that doesn't match the owner type

Paste a customer GID into a row that says PRODUCT and ImportKit catches it before the write:

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

This is the guard that stops a mis-sorted spreadsheet writing metafields onto the wrong resources.

Value formats

Values are converted based on the metafield's type, taken from the existing definition or your type column. The short version:

• Lists. "Breathable, Pre-washed, Recycled" becomes a three-item array. If the cell contains line breaks, newlines become the separator instead, so items can contain commas.
• Rich text. Plain text, HTML or Shopify's own rich text JSON are all accepted and converted appropriately.
• Structured types. money, rating, weight, dimension and volume take a small JSON object. Quote the cell.
• Blank cells write nothing. You can't clear a value by emptying the cell.

The full value format reference →

Re-importing values that already exist

A value is identified by owner_type + owner_reference + namespace + key. The pre-import check compares against the value currently in your store and shows what it is, which makes it genuinely useful before a bulk update:

A full walkthrough of a bulk update →

Common patterns

Several metafields on the same product

One row per value, repeating the owner reference:

owner_type,owner_reference,namespace,key,value
PRODUCT,merino-crew-neck,custom,care_guide,Hand wash cold
PRODUCT,merino-crew-neck,custom,fabric,100% merino wool
PRODUCT,merino-crew-neck,custom,country_of_origin,Portugal

Reshaping a wide export into rows

Exports usually have one row per product and one column per field. ImportKit needs one row per value. In a spreadsheet, the quickest route is to build one block per field and stack them: copy the handle column, add a constant key column, and paste the values. Repeat for each field, then concatenate the blocks into one sheet.

Store-wide values

owner_type,owner_reference,namespace,key,value,type
SHOP,,custom,store_motto,Built to last,single_line_text_field
SHOP,,custom,support_hours,"Mon-Fri, 9am-5pm CET",single_line_text_field

Next