Getting started

The quick start gets you through one import. This page explains the model underneath it, so you can plan a real migration rather than following steps.

What ImportKit is for

Shopify can import products and customers from a CSV out of the box. What it can't import is the custom data layer: the metafields and metaobjects you define to hold everything Shopify's built-in fields don't cover. Normally you build those one at a time in the admin, then fill them in product by product.

ImportKit imports that layer. Five content types:

Type	One row is…	Typical use
Metafield definitions	one field definition	Setting up 30 product fields without 30 trips through the admin.
Metafield values	one value on one resource	Filling in a care guide on 400 products from a supplier sheet.
Metaobject definitions	one custom content type, with all its fields	Creating an “Author” or “Size chart” structure.
Metaobject entries	one entry of a definition	Loading 200 store locations or 50 ingredients.
Blog articles	one article	Migrating a blog off WordPress, with metafields attached.

Definitions versus values

This is the single distinction worth getting straight, because two of the five import types are about each side of it.

A definition is the shape of the field.: “Products have a field called custom.care_guide, it holds multi-line text, and it shows up on the product page in the admin.” It exists once per store. You create these with metafield definitions.
A value is what's in that field on one resource.: “This particular t-shirt's custom.care_guide says Hand wash cold.” There's one per resource. You set these with metafield values.

The same split applies to metaobjects: metaobject definitions describe the structure (“an Author has a name, a bio and a photo”), and metaobject entries are the actual authors.

Order matters

Import definitions before values. A value import can succeed without a definition if you supply a type column, but you'll get a better-behaved store (pinned fields, validations, proper admin UI) if the definition goes in first.

Every import has the same four steps

Choose a content type and target

The content type decides which columns exist. Two types also need a target: blog articles need to know which blog, and metaobject entries need to know which definition. For metaobject entries the target actually changes the available columns, because they come from that definition's own fields.
Upload a CSV

ImportKit reads the header row and lists your columns with a few sample values from each. The file is read as a stream, so a large one doesn't have to fit in memory. File requirements →
Map columns to fields

Headings that look like a field's key or label are matched for you. Pick the Shopify field for any other column from the dropdown, or set it to Ignore. Ignored and unmapped columns are never sent to Shopify, though the full uploaded row is kept with the job record. Mapping in detail →
Check, then import

For every type except blog articles, a free read-only pre-import check gives every row a verdict and totals the credits needed. Then Start Import runs the job on our servers with live progress. Running an import →

Where things live in the app

Page	What it's for
Home	Your credit balance (available, purchased, used) and your five most recent imports with their status.
Import	The four-step wizard. Also where the template and column-guide downloads live.
Credits	Your balance and the four credit packs. Purchases are approved on Shopify's own charge screen.
Jobs	Every import you've ever run. Active jobs show live progress; finished ones open to per-row results and a download of rows needing attention.

How you pay

ImportKit is free to install, and everything up to the moment of writing is free: templates, uploads, mapping, and unlimited pre-import checks. Imports cost one credit per row written.

Credits come in one-time packs, from 50 for $1.99. No subscription, and credits don't expire while the app is installed.
A credit is reserved just before each row is sent and released if the row isn't written.
Rows that skip, conflict, error or get interrupted are refunded automatically.
Run the pre-import check to see the exact cost before you commit.

Credits and billing in full → · Pack prices →

What ImportKit can and can't touch

ImportKit doesn't ask for access to your customers or orders yet, so the app cannot read that data at all. It also means customer and order metafields can't be written yet. That arrives with customer and order support, which is coming very soon.

Rows targeting them aren't silently dropped. They're reported individually with the exact missing permission, and the rest of the file still imports. The owner type dropdown on the mapping step only lists owner types your store's granted permissions actually cover, so you'll usually see this before you even build a file.

The full permissions reference →

What it doesn't do

Read this before planning a migration around it.

No undo, no rollback, no deletion. An import creates or updates. Reversing one is manual work in the Shopify admin. This is why the pre-import check exists.
It won't create the resources you're tagging. A metafield value needs a product, page, collection or article that already exists.
Blank cells behave differently by type. For metaobject entries and blog articles, an empty cell is skipped, not written. For metafield values, a blank value is sent to Shopify as-is, so leave out any rows you don't want to change.
Blog articles have no duplicate detection. Articles aren't uniquely keyed, so running the same file twice creates them twice. There's no check step for that type either.
Articles are always published. There's no draft or status column for article imports.
Field and definition types are immutable. Shopify won't let a metafield's type change after creation, so a row whose type differs from the existing definition is reported as a conflict rather than silently doing something surprising.

The rest of the deliberate limitations, with reasoning →

Testing safely

Because imports can't be reversed, the cheapest insurance is a dry run somewhere that doesn't matter.

Use a development store. Install ImportKit there and run the real file. A Starter Pack is usually enough for a rehearsal.
Or split the file. Copy the header row and five data rows into a second file, import that into production, and check the result in the Shopify admin before running the rest.
Always run the pre-import check. It costs nothing and catches invalid keys, unknown owner types, reserved namespaces, missing references, duplicate rows within the file (for definitions and metaobject entries) and type conflicts with existing definitions.
Start with conflict mode set to Skip. It's the default for a reason: the worst case is that nothing happens.

Checklist before a live import

The file is a .csv, saved as UTF-8. How to export one →
The header row is the first row, with no title row above it.
Definitions are imported before the values that use them.
The resources you're setting values on already exist in the store.
You've run the pre-import check and read the verdicts, not just the totals.
Every row reported as an error has been fixed or removed.
You've chosen the conflict mode deliberately, rather than leaving the default by accident.
Your balance covers the “N of M rows will be written” figure.
You know what you'd do to undo it, given that ImportKit won't.

Preparing your CSV

Encoding, quoting, lists, blank cells, limits, and the mistakes spreadsheets introduce.

All import types compared

Which need a target, which support the check, which have templates.