Docs › How an import works

Mapping columns

Step 2 of the wizard. You tell ImportKit which of your CSV columns feeds which Shopify field. Nothing is inferred from your header names, which is why any export from anywhere is usable without renaming a thing.

How it works

ImportKit reads your file's header row and lists each column, with a few sample values underneath so you can see what's actually in it. Next to each column is a dropdown of the Shopify fields available for the import type you chose, plus Ignore.

Columns whose names match a known field are pre-selected for you, so a downloaded template arrives fully mapped. Everything else is yours to set.

Your header names are irrelevant

This file has nothing in common with ImportKit's column names, and imports exactly like the template does:

Field name,Field key,Data type,Attaches to,Internal note
Care guide,care_guide,multi_line_text_field,PRODUCT,added by marketing
Fabric,fabric,single_line_text_field,PRODUCT,from supplier sheet

Map it like this:

No renaming, no reordering, no cleaning up the export first. This matters more than it sounds — most real imports start as somebody else's spreadsheet.

Ignore, and unmapped columns

Set a column to Ignore and it's dropped before the row reaches the importer. Same for any column you simply leave unmapped. In both cases:

• the contents never reach Shopify;
• the contents aren't stored with the job;
• nothing about the row's outcome changes.

So an export with thirty columns of internal notes, prices, stock levels and staff comments is completely safe. Map the four you need and ignore the rest.

Required fields

Each import type has fields that must be mapped before you can continue. For metafield definitions that's Name, Key, Type and Owner type; for metafield values it's Owner type, Key and Value; for blog articles just Title.

If one is unmapped, the wizard tells you which. It's a hard stop rather than a warning, because the alternative is importing hundreds of rows that all fail for the same reason.

The full required list for each type is on its own page — see all import types.

One column, one field

Each CSV column maps to at most one Shopify field. If you need the same source value in two fields, duplicate the column in your spreadsheet and map each copy. Cheap to do, and it keeps the mapping unambiguous.

Reading the field list

Each field in the dropdown carries information worth glancing at:

Help text

What the field controls, and what values it accepts. For metafield values, the Owner reference field's help text points you at the per-owner-type formats.

Required markers

Fields you must map to proceed.

Constrained values

Where your store's granted permissions narrow what a column can contain, ImportKit says so prominently — as a banner above the table, listing exactly which values are available. The owner type column is the usual case. Why →

Metafield columns on article imports

For blog articles the dropdown includes your store's article metafield definitions alongside the standard fields, keyed namespace.key — so custom.reading_time appears as a mappable target next to Title and Body.

Metaobject reference fields appear too, labelled as references, letting you link an article to an entry by handle in the same row.

Refresh fields

The field list is read from your store when you reach the mapping step. If you create a definition in the Shopify admin — or run a definitions import in another tab — while the wizard is open, press Refresh fields to pick it up without starting over.

This is the normal move when you realise mid-flow that the metafield you wanted to map doesn't exist yet.

When the field list depends on your target

For metaobject entries the mappable fields are generated from the definition you selected as the target, so they differ per definition. Change the target and the field list changes with it.

The upload step's Show column reference table is the fastest way to see what a given definition needs before you build the file.

Mapping mistakes and how they show up

All of these are free to discover and free to fix. Mapping happens before anything is written, and going back a step costs nothing.

Next