Docs › Start here

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:

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.

Every import has the same four steps

1. 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.

2. 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 →

3. Map columns to fields

   Pick the Shopify field for each column, or set it to Ignore. Your header names don't need to match anything — mapping is always explicit. Ignored and unmapped columns are dropped before the import runs. Mapping in detail →

4. 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

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, no expiry.
• 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 deliberately doesn't ask for access to your customers or orders. That keeps the app out of Shopify's protected customer data review, and it means the app cannot read that data at all — but it also means customer and order metafields are out of reach.

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 deliberately won'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 don't clear values. An empty cell is skipped, not written, so you can't blank out an existing value by leaving the cell empty.
• 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.

1. Use a development store. Install ImportKit there and run the real file. Credit purchases on development stores are test charges, so rehearsing costs nothing.
2. 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.
3. Always run the pre-import check. It costs nothing and catches invalid keys, unknown owner types, reserved namespaces, duplicate rows within the file and type conflicts with existing definitions.
4. 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.

Next