Importing data
Matching rules, validation levels, images, metafields and partial updates - everything that decides whether an import does what you meant.-
An import takes a spreadsheet and applies it to your store. The difficulty is never the upload - it is making sure each row updates the record you intended instead of creating a new one. This page covers the rules that decide that.
Supported files and sources
Drag and drop, or browse. Accepted formats:
| Format | Notes |
|---|---|
.xlsx |
Recommended. Preserves types, handles commas in text, no encoding issues. |
.xls |
Legacy Excel. Supported, but convert to .xlsx if you can. |
.csv |
Must be UTF-8. Save as “CSV UTF-8” in Excel, not plain CSV. |
Paste a direct link to a file and Migrato downloads it at run time. Useful for supplier feeds that update at a fixed address.
https://supplier.example.com/feeds/products.csv
The URL must be publicly reachable without a login. Test it in a private browser window first.
Share the sheet with Anyone with the link can view and paste the link. Migrato reads the first worksheet unless you specify another.
A shared sheet plus a scheduled import means your merchandiser edits a spreadsheet and the store updates itself overnight.
Configure the connection once in Settings → Connections, then choose a folder and file pattern. Available on Basic and above.
Host sftp.supplier.com Port 22 Path /outbound/daily/ Pattern products_*.csv
-
Create versus update: how matching works
For every row, Migrato asks one question: does a record matching this key already exist? If yes, it updates. If no, it creates. Getting the key right is the whole game.
| Data type | Matched by | If a match is found |
|---|---|---|
| Products | Handle, or Variant SKU |
Product is updated; only columns present in your file change |
| Variants | Variant SKU, or option values |
Variant is updated in place |
| Customers | Email |
Customer profile is updated; addresses are added, not replaced |
| Collections | Handle |
Collection is updated; products are added to it |
| Orders | Name (e.g. #1001) |
Tags, notes and fulfilment status are updated |
| Inventory | Variant SKU + location |
Level is set to the value you supply |
| Redirects | Path |
Target is updated |
If your file has a SKU that does not exist in the store, Migrato has no way to know you meant an existing variant. It creates a new one. This is why the preview counts matter more than any other screen in the app.
-
Partial updates are safe by design
Columns you do not include are never touched. This is the single most useful property of the import engine, and it makes narrow files the safest files.
# To change only prices, upload exactly this: Handle Variant SKU Variant Price blue-cotton-tshirt TS-BLU-M 26.00 blue-cotton-tshirt TS-BLU-L 26.00 oak-side-table FUR-OAK-01 159.00 # Descriptions, images, tags and inventory are untouched - # the file physically cannot affect them.
An empty cell in a column you did include can be read as an instruction to clear that field. If you do not want a field touched, delete the whole column rather than emptying its cells.
Validation levels
Before any import runs, every row is checked against your live store. Issues are reported at three levels.
Importing images
Images are supplied as publicly reachable URLs in the Image Src column. Migrato downloads each one and attaches it to the product.
Repeat the handle on additional rows and put one URL in each. Image Position controls the order.
| Handle | Image Src | Image Position |
|---|---|---|
| blue-cotton-tshirt | https://cdn.example.com/blue-front.jpg | 1 |
| blue-cotton-tshirt | https://cdn.example.com/blue-back.jpg | 2 |
| blue-cotton-tshirt | https://cdn.example.com/blue-detail.jpg | 3 |
Separate URLs with a semicolon. Order in the cell becomes image order on the product.
Handle Image Src blue-cotton-tshirt https://cdn.example.com/a.jpg;https://cdn.example.com/b.jpg
Add Variant Image on the variant’s own row. The URL must also appear in the product’s image list, or Migrato adds it there for you.
Use Image Alt Text to set accessibility text at the same time. It is good for SEO and takes no extra work.
The most common image failure is a URL behind a login, on an internal network, or with an expiring token. Test a sample in a private browser window before importing a few thousand of them.
Metafields use a structured column header carrying the namespace, key and type together.
Header format Metafield: namespace.key [type] Examples Metafield: custom.material [single_line_text_field] Metafield: custom.warranty_years [number_integer] Metafield: custom.care [list.single_line_text_field] Metafield: custom.launch_date [date]
| Type | Expected value | Common mistake |
|---|---|---|
single_line_text_field |
Plain text | - |
number_integer |
10 |
Decimal point present |
number_decimal |
10.5 |
Comma decimal from a European locale |
boolean |
true / false |
Yes, 1 or TRUE |
date |
2026-08-18 |
Excel reformatting to 18/08/2026 |
list.* |
["Cotton","Linen"] |
Writing Cotton, Linen as plain text |
*_reference |
gid://shopify/Product/123 |
Using a handle instead of an ID |
-
Full detail, including definitions versus loose metafields, is in Getting metafields right when you edit in bulk.
Large files and performance
Rather than one enormous file, import collections first, then products, then customers, then orders. Each job is faster, easier to verify, and a problem in one does not hold up the others.
-
Undoing an import
There is no single undo button, and deliberately so - but there is a reliable pattern.
- Before any significant import, export the records you are about to change with the same columns. Name the file with the date.
- Run your import.
- If the result is wrong, import the before file. Because matching updates rather than duplicates, the previous values are restored exactly.
- For records that were newly created and should not exist, import the same file with a
Commandcolumn set toDELETE.
A DELETE command removes the record from Shopify. There is no recycle bin. Always run a delete on a ten-row slice first and confirm it removed exactly what you expected.