Our first app, Migrato, is live on the Shopify App Store - free plan, no credit card. Take a look
Home / Documentation / Importing data
Guides

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.

File URL
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.

★

Live sheets work well for teams

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.

SFTP source
 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
!
A missing SKU is the number one cause of duplicates

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.

Minimal price update
# 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.
✕
Blank cells are not the same as absent columns

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.

Errors - row is skippedMissing required fields, malformed prices, invalid option combinations, references to locations that do not exist.
Warnings - row runs, flaggedUnreachable image URLs, duplicate handles within the same file, unusually long titles, prices of zero.
Notices - informationalNew vendors or tags that will be created, currency rounding, values truncated to Shopify's field limits.
Clean rowsNothing to report. These run exactly as previewed, with no surprises.

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.

Semicolon-separated
 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.

★

Alt text

Use Image Alt Text to set accessibility text at the same time. It is good for SEO and takes no extra work.

!
Image URLs must be public

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.

Metafield columns
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

Large files and performance

Processing speed
Roughly 10,000 products in 15–30 minutes, depending on how many images each one has.
Rate limits
Jobs are batched to stay inside Shopify's API limits. You will never see a throttling error.
Parallel threads
Pro runs up to 4 threads per job, Premium 10 or more. Same file, a fraction of the time.
Closing the tab
Safe at any point. Jobs run on our servers and email you when they finish.
Images
The slowest part of any import. A catalogue with five images per product takes noticeably longer than one without.
★
Split very large migrations by data type

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.

    1. Before any significant import, export the records you are about to change with the same columns. Name the file with the date.
    2. Run your import.
    3. If the result is wrong, import the before file. Because matching updates rather than duplicates, the previous values are restored exactly.
    4. For records that were newly created and should not exist, import the same file with a Command column set to DELETE.
✕
Deletion is permanent

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.

Ready to run this on your own store?

Migrato's free plan handles 25 items per job - enough to follow any page in these docs end to end before you pay anything.

Free plan forever No credit card 2-minute setup Uninstall anytime