Docs › How an import works

The pre-import check

A read-only pass over your whole file that reports, per row, exactly what the real import would do. It never writes anything, never consumes credits, and you can run it as many times as you like.

When you get one

Four of the five import types get a check: metafield definitions, metafield values, metaobject definitions and metaobject entries. All four are uniquely keyed, so ImportKit can compare your file against your store and predict each row's outcome.

Blog articles don't. Articles aren't uniquely keyed — there's nothing to compare against — so step 3 for that type is a preview of how the first row maps instead.

The five verdicts

The counts appear as badges across the top, along with the headline figure: “N of M rows will be written”. That N is precisely what the import will cost in credits.

The per-row report

Every row appears with:

• its row number, 1-based and excluding the header, so it matches your spreadsheet;
• a label that identifies it in your terms — PRODUCT · custom.care_guide, or the metaobject type, or the entry handle;
• its verdict;
• any issues, each marked as an error or a warning.

Where a row collides with something existing, the report identifies what it collided with. For metafield values it shows the value currently in your store, which is what makes the check genuinely useful before a bulk overwrite.

Errors versus warnings

Error — the row cannot import

Fix it in your file, or delete the row. Errored rows are never charged.

Warning — the row will import, with a caveat

Worth reading. A warning usually means something resolved less precisely than you intended: a metaobject reference that couldn't be narrowed to a specific definition, or an unrecognised metafield type that Shopify might still accept.

What it catches

All of this is found before a single credit is spent:

• Missing required values — name is required.
• Invalid keys — spaces or punctuation where only letters, numbers, hyphens and underscores are allowed.
• Misspelled owner types, with a suggestion — ownerType "PRODUCTS_VARIANT" is not valid — did you mean "PRODUCTVARIANT"?
• Reserved namespaces — shopify--, app-- and friends belong to Shopify and apps.
• Unrecognised metafield types, as a warning with a suggested spelling.
• Duplicate rows within the file — the second occurrence is flagged duplicate of row N rather than quietly colliding halfway through the import.
• Type conflicts with existing definitions — a metafield's type is immutable in Shopify, so a row that would change it is reported rather than attempted.
• Owner references that don't resolve — a product handle that doesn't exist, an ambiguous SKU, a GID belonging to a different resource type than the row claims.
• Owner types your permissions don't cover — with the exact missing permission named. One blocked owner type doesn't block the file; the rest still imports, and the credit estimate counts only the rows that will be written.

A file that's wrong in five ways

Worth trying once, so you recognise the output. Every row here is broken differently:

name,key,type,ownerType,namespace
,care_guide,multi_line_text_field,PRODUCT,custom
Bad key,care guide,multi_line_text_field,PRODUCT,custom
Bad owner,valid_key,multi_line_text_field,PRODUCTS_VARIANT,custom
Reserved namespace,valid_key,multi_line_text_field,PRODUCT,shopify--foo
Typo in type,another_key,multi_line_text_fied,PRODUCT,custom

Choosing a conflict mode

The conflict mode selector sits on the check step, above the report. Change it and press Re-check to see the same file's verdicts under the new setting — rows that were skips become updates, or conflicts, and the credit total changes with them.

Re-checking is free, so trying all three before deciding costs nothing but a moment. Conflict modes in detail →

The loop to get into

1. Run the check

   Read the badges, then read the rows. The totals hide the interesting parts.

2. Fix the errors in your spreadsheet

   Row numbers in the report match your file, excluding the header — so report row 12 is spreadsheet row 13.

3. Re-upload and re-check

   Repeat until the only rows left are the ones you intended. Still free.

4. Read the warnings once more

   They're the things that will import slightly differently than you assumed.

5. Confirm the credit figure, then import

   “N of M rows will be written” should match what you expect to happen.

When everything is blocked

If no row in the file is importable, the wizard blocks rather than letting you start a job that can only fail. The report tells you why — usually one systematic mistake, like an owner type column mapped to the wrong CSV column.

Large files skip the check

The check reads every row at once, because duplicate detection and credit totalling are whole-file questions. That gives it a lower ceiling than the import itself:

Above those, you'll see a “This file is too large to preview” notice and the import is still allowed. You lose the preview, not the safety: every row is still checked against your store as it's imported, and your conflict mode is applied per row in exactly the same way.

If you'd rather keep the preview, split the file into parts under 50,000 rows. Rows are independent, so splitting is safe. All limits →

What the check can't tell you

Two honest caveats:

• It's a snapshot. It reflects your store at the moment it ran. If you change definitions in the Shopify admin afterwards, re-check before importing.
• Shopify has the last word. The check catches everything ImportKit can verify locally or by reading your store, but Shopify can still reject a row for a rule the check didn't model — an unsupported capability for a given type, for instance. Those rows fail during the import and are refunded.

Next