Shopify CSV Import: How to Format Your File Without Errors

A Shopify CSV import file is a comma-separated spreadsheet that maps your product data — titles, prices, images, variants, and inventory quantities — into the exact format Shopify's admin panel expects. Get the formatting right and you can upload hundreds of products in minutes. Get it wrong and the entire file gets rejected.

Most failed Shopify imports trace back to the same handful of formatting mistakes. This guide walks through every column, every rule, and every common error so your next CSV upload works on the first try.

Start With the Official Template

Download Shopify's product CSV template directly from your admin panel under Products > Import > Download a sample CSV. This gives you the exact column headers Shopify expects. Do not rename, reorder, or delete any headers — they are case-sensitive, and a single mismatch will cause the import to fail.

The template includes over 25 columns, but only two are technically required: Title (for new products) and Handle (when adding variants to existing products). Every other column is optional, though leaving key fields blank means Shopify will either skip them or apply defaults.

Column-by-Column Essentials

Here are the fields that cause the most confusion:

• Handle — A unique, URL-safe identifier for each product (e.g., blue-cotton-tshirt). Shopify generates this automatically if left blank on new products, but you need it when adding multiple variants to the same product across rows.
• Title — The product name customers see. Required for every new product row.
• Variant SKU — Your internal stock-keeping unit. Not required, but essential for inventory tracking.
• Variant Price — Use numbers only, no currency symbols. Enter 29.99, not $29.99.
• Image Src — A direct, publicly accessible URL starting with https://. Images must be under 25 megapixels (5,000 x 5,000 pixels max). Broken or private URLs are the single most common import error.
• Option1 Name / Option1 Value — Required whenever you include variant-related columns like SKU or weight. For a t-shirt with sizes, set Option1 Name to Size and Option1 Value to Small, Medium, or Large on separate rows sharing the same Handle.

Encoding and File Rules

Three formatting rules prevent the majority of failed imports:

If your file exceeds 15 MB, split it into smaller batches. Most spreadsheet editors let you export a subset of rows into a separate file. Import each file sequentially.

How to Handle Variants Correctly

Variants are where most CSV imports break down. Each variant of a product gets its own row, and all variant rows share the same Handle. Only the first row for each product includes the Title, Description, and other product-level fields — leave those cells blank on subsequent variant rows.

For example, a t-shirt in three sizes needs three rows:

Duplicate option values under the same handle (two rows both saying "Medium") will trigger an error.

The 6 Most Common Errors and How to Fix Them

Save Time With a Managed Service

If your products come from vendor invoices rather than a tidy spreadsheet, formatting a CSV from scratch adds hours of work before you even start the import. Services like Goodness Logic convert vendor invoices directly into publish-ready Shopify listings — images, descriptions, tags, and all — without you touching a CSV file.