Import CSV Shopify: how to transfer your products

Shopify's built-in CSV import is one of those tools that looks approachable until you actually try to use it for a real migration. The template is clean, the documentation exists, and the Admin UI makes it seem straightforward. Then you hit a catalog with 3,000 products, each with three variants and four images, and discover that the format has rules that are not obvious until they break your import.

This guide walks through the CSV format in detail, explains the rules that trip up most people, and covers where the tool stops being practical — and what to use instead.

The Shopify product CSV format

Shopify publishes an official CSV template, and the structure is row-per-variant, not row-per-product. This is the single most important thing to understand before you format your data.

A product with three variants — Small, Medium, Large — occupies four rows in the CSV: one row for the product itself and one additional row for each subsequent variant. The product-level fields (title, description, vendor, type, tags, SEO metadata) appear only on the first row. The variant rows carry only variant-specific fields and must have the same Handle value as the product row.

Mandatory columns

The absolute minimum set of columns for a working import:

• Handle — URL-safe, unique identifier for the product (e.g., blue-wool-sweater). Shopify derives the product URL from this. If two rows share a Handle, they are treated as variants of the same product.
• Title — product name, first row only.
• Body (HTML) — product description, HTML allowed, first row only.
• Vendor — brand or supplier name.
• Standardized Product Type — maps to Shopify's taxonomy. Leave empty if you are not using taxonomy.
• Published — TRUE or FALSE.
• Variant Price — required on every row, including subsequent variant rows.
• Variant Inventory Policy — deny to stop selling when out of stock, continue to allow overselling.
• Variant Fulfillment Service — typically manual unless you are using a third-party fulfillment provider.
• Variant Requires Shipping — TRUE or FALSE.
• Variant Taxable — TRUE or FALSE.

Variant columns

Shopify supports up to three option dimensions per product (Option1 Name, Option1 Value, Option2 Name, Option2 Value, Option3 Name, Option3 Value). Each variant row fills in the corresponding option values.

For a product with Color and Size options, your rows look like this:

Handle,Title,Option1 Name,Option1 Value,Option2 Name,Option2 Value,Variant SKU,Variant Price,Variant Quantity
blue-sweater,Blue Wool Sweater,Color,Blue,Size,Small,BSW-BLU-S,89.00,12
blue-sweater,,Color,Blue,Size,Medium,BSW-BLU-M,89.00,8
blue-sweater,,Color,Blue,Size,Large,BSW-BLU-L,89.00,5

Note that Title (and all other product-level fields) is empty on rows 2 and 3. Shopify uses the Handle to group them and pulls the product-level data from the first row.

Image columns

Images work differently from other fields. You provide URLs in the Image Src column, and Shopify downloads them during import. Local file paths do not work — images must be publicly accessible via HTTPS.

For multiple images on a single product, you add additional rows. These image rows carry the Handle and Image Src but no other variant or product data:

Handle,Title,Image Src,Image Position,Image Alt Text
blue-sweater,Blue Wool Sweater,https://example.com/img/bsw-front.jpg,1,Blue wool sweater front view
blue-sweater,,,https://example.com/img/bsw-back.jpg,2,Blue wool sweater back view

The Image Position column controls display order. If you skip it, images appear in import order.

The 15 MB file size limit

This is the constraint that kills most large catalog imports. Shopify enforces a 15 MB limit on CSV uploads through the Admin panel. For context, a catalog with 5,000 products, each with a 500-character description and three variants, will produce a CSV somewhere between 8 MB and 20 MB depending on your description lengths and image URL counts.

If your catalog exceeds this limit, you have three options:

Split the file. Divide your product list into batches under 15 MB each and import sequentially. The main risk is making sure you do not accidentally duplicate the product rows across files when splitting variant groups.

Use the Shopify CLI. The CLI does not have the same file size restriction as the UI. You can upload larger files via shopify product import if you are comfortable with the command-line workflow.

Use a third-party import tool. Matrixify (formerly Excelify) is the most widely used alternative for large catalog imports. It accepts files up to 1 GB, supports Excel format in addition to CSV, handles complex import logic (upserts, conditional updates), and provides row-by-row error logs. For stores with more than 2,000 products, Matrixify is generally the better choice.

Common errors and how to fix them

"Could not find variant"

This error appears when variant rows reference option names or values that do not match the product's first row. Option names are case-sensitive and must be identical across all rows sharing a Handle. Color and color are different values.

Images not importing

Usually caused by image URLs that are not publicly accessible — either behind a login, using HTTP instead of HTTPS, or returning non-200 status codes. Test each image URL in a browser tab before import. If your images are coming from a PrestaShop store that requires a session cookie, they will fail.

Duplicate products after re-import

If you import the same CSV twice, Shopify will create duplicate products unless you use the "Overwrite" option. The overwrite logic works by matching on Handle — if a product with that Handle already exists, it updates instead of creating. If your Handles change between imports (e.g., because you regenerated them from a different source), you will get duplicates.

Encoding issues with special characters

Shopify expects UTF-8. If your CSV was exported from PrestaShop using a latin1 or Windows-1252 encoding, product descriptions containing é, ê, ü, or similar characters will display as garbage. Always open your CSV in a text editor that shows encoding (VS Code, for example) and confirm it reads correctly before upload.

The 100-variant limit

Shopify limits products to 100 variants by default. A product with three options — Color (5), Size (5), Material (4) — would produce 100 variants (5 × 5 × 4), which is exactly at the limit. If your PrestaShop store has products with more than 100 combinations, the CSV import will fail for those products. You will need to either reduce the option matrix, split the product, or use the productSet GraphQL mutation which handles the variant creation differently.

When CSV import is not the right tool

For migrations from PrestaShop specifically, CSV import has a structural problem: PrestaShop's data model does not map cleanly to Shopify's CSV format. Variants in PrestaShop are stored with price impacts (an amount added to the base price), not absolute prices. Categories become collections. Custom fields stored in PrestaShop attributes need to become Shopify metafields. None of this transformation logic is handled by the CSV format itself.

If your catalog has more than 1,000 products, uses variants extensively, or has custom attribute data you want to preserve as metafields, a direct API-based migration is significantly cleaner than the CSV path. The Shopify GraphQL Admin API's productSet mutation handles upserts, variant creation, metafield population, and inventory assignment in a single operation per product — without the 15 MB limit, without encoding issues, and with proper error handling per entity rather than a single failed import that requires debugging a 50,000-row file.

WarpForge uses the GraphQL API rather than CSV specifically because of these limitations. The productSet mutation allows products with all their variants, images, and metafields to be created or updated atomically, with inventory set via inventorySetQuantities in a follow-up call. For large catalogs, this approach is also significantly faster: batching 250 products per API call (Shopify's current limit for productSet) against the rate limit of 2 requests per second means a 10,000-product catalog can be imported in under 20 minutes — versus a multi-hour manual process with CSV.

Practical checklist before you import

Before you click the import button, verify:

• File encoding is UTF-8 (open in VS Code or Notepad++ and confirm)
• All Handles are URL-safe (no spaces, no accents, no special characters except hyphens)
• Variant rows have the same Handle as their product row
• Option names are consistent in casing across all rows for a given product
• All image URLs are publicly accessible via HTTPS
• File size is under 15 MB or you are using Matrixify
• You have a backup of your current Shopify catalog if you are using the Overwrite option on an existing store

The CSV import is a usable tool for simple catalogs and quick tests. For a full PrestaShop migration, treat it as a fallback rather than the primary method.