How to Import and Update Shopify Products in Bulk Using CSV

A Shopify bulk upload adds or changes many products at once by importing a product CSV file in your Shopify admin. A standard import creates new products, and the overwrite option lets the same file update products already in your store. Merchants use it to launch a catalog, move from another platform, work from supplier spreadsheets or make mass price and detail changes.

Most failed or harmful uploads come from how the file is built and how overwriting behaves. A badly structured CSV can be rejected, or it can replace good product data. This guide covers the import itself and the rules that prevent those problems.

How to import products with a CSV file

Before your first full upload, test the process with a small file of a few products, including at least one product with variants and images. Check the results in the admin before you scale up. If you are updating existing products, export your current catalog first and keep that file as a backup, as described in the update section below.

Shopify updates its admin from time to time, so button names may differ slightly from the wording below. Follow the order of the steps rather than looking for exact labels.

1. Prepare your CSV file using the rules in the next section.
2. In your Shopify admin, go to Products and choose the import option.
3. Add your CSV file from your computer.
4. Decide whether to overwrite products with matching handles. Leave this option unselected when every row is a new product. Select it only when the file is meant to update products that already exist in your store.
5. Upload the file and review what Shopify shows you. If the file has a structural problem, Shopify displays an error message at this stage instead of importing it.
6. Confirm the import.

Shopify lists imported products in the order they appear in your CSV, so sort the rows beforehand if you want related products to sit together in the admin. Large files take longer to process, and you receive a notification when the import is complete.

Build a product CSV that Shopify will accept

Shopify accepts a product CSV when it has the right headers, the right row layout and values in the expected formats. Creating new products needs very few columns, and a mistake usually means only that a row fails. Updating existing products requires more identifying columns, and a mistake can change data that was already correct.

Start from Shopify’s sample file

The safest base is Shopify’s own template. You can download the sample product CSV from Shopify’s Help Center. It contains two example products with variants, so delete those rows before adding your own, or the examples will be imported into your store.

The sample includes an Inventory quantity column, but that column only works for stores with a single location. If you stock products in more than one location, leave quantities out of the product file and set them with Shopify’s separate inventory CSV.

Keep the file structure strict:

• The first line must contain the column headers, named exactly as they appear in Shopify’s column list.
• Columns must be separated by commas.
• Save the file as UTF-8 with LF (Unix-style) line endings, which most spreadsheet and text editors can select on export.

Use Shopify’s current column names, such as URL handle, Description and Barcodes, rather than older names like Handle, Body (HTML) and Barcode. If you calculate prices or other values with spreadsheet formulas, only the resulting values are saved in the CSV, so check the computed cells before you export.

Required columns and URL handles

The URL handle is the product’s unique identifier. Shopify uses it to decide which rows belong to which product, and it also appears in the product page URL. If you leave it blank on a new product, Shopify creates it from the Title, so “Black Sunglasses” becomes black-sunglasses.

A handle can contain only letters, numbers and dashes, with no spaces. Each product needs its own handle, because Shopify treats rows that share a handle as the same product.

Row structure for simple products and variants

Shopify reads a product as a group of rows that share a URL handle. For a simple product, the first row holds all product fields and the first image URL, and each following row contains only the URL handle and one additional image URL.

For a product with variants, the first row holds all product fields, the first variant and the first image. Each following row repeats the URL handle, leaves Title, Description, Vendor and Tags empty, and fills in the next variant’s details and any image URL.

Variants follow a few fixed rules:

• A product can have up to 3 options, such as Size, Color and Material.
• A product with only one option uses “Default Title” for that option.
• Each variant needs a unique combination of option values, so two Small / Red rows on the same product will conflict.
• All rows for one product must sit next to each other in the file.

Variant-level fields such as SKU or Weight value (grams) only work when the Option1 name and Option1 value columns are included. Keep those columns in the file whenever you add or change variant data.

Column formats and defaults

Many errors come from values in the wrong format, and unintended settings usually come from defaults. When you leave a column out or a cell empty, Shopify applies these defaults:

• Price: a bare number with no currency symbol, such as 19.99. The default is 0.00.
• Weight value (grams): a whole number in grams with no unit, so 5.125 kg becomes 5125 and 4 lb becomes 1814. The default is 0, and Weight unit for display defaults to kg.
• Inventory quantity: defaults to 0 (single-location stores only).
• Published, Charge tax and Requires shipping: each defaults to true.
• Continue selling when out of stock: defaults to deny.

If a product should stay hidden or be tax-exempt, set those columns explicitly so it doesn’t go live or start charging tax. Status works differently: if you leave the column out, products import as active, but if you include it, every row needs a valid value of active, draft or archived.

Several other columns have specific formatting rules:

• Tags: one cell, separated by commas, with a maximum of 250 per product. Use letters, numbers and hyphens, and avoid accented characters and symbols. If you edit the file in a plain-text editor, put quotation marks around the tag cell yourself.
• Barcodes: up to 20 barcodes separated by semicolons, with an optional type prefix such as gtin:00012345678905. Barcodes without a prefix import as Custom. A file that includes both the old Barcode column and the Barcodes column fails to import.
• Packed product dimensions: length, width, height and dimension unit (cm or in) must all be filled or all be blank. If only some are filled, the product is not imported. Omitting all four columns leaves saved sizes unchanged, but four empty cells on a variant row clear that variant’s saved size.
• Product category: a value from Shopify’s Standard Product Taxonomy, either the full breadcrumb or its ID. Shopify uses it to calculate US tax rates. Type, by contrast, is a free-form label you define.
• SKU and fulfillment service: a variant that uses a custom fulfillment service cannot have a blank SKU. The service must already exist in your admin and be written in lowercase with dashes.
• SEO title and SEO description: up to 70 and 320 characters respectively. They fall back to the product Title and Description.

You cannot create gift cards through the product CSV.

Add product images

A CSV holds text only, so you add images by entering their URLs. Each image must be hosted at a public https address that opens without a password or login. Shopify downloads every image during the import and stores its own copy, so the original links aren’t needed afterward.

Where the URLs come from depends on your situation:

• New images on your computer: upload them to Content > Files in the Shopify admin, which generates a URL for each file and accepts many files at once. Then copy those URLs into your CSV.
• Moving from another platform: reuse the image URLs from your current store, as long as they are public and use https.
• A file exported from Shopify: the export already contains working image URLs.

The first image sits on the product’s main row, and each additional image goes on its own row for the same product. Use the Image position column to set the display order, starting with 1. If a variant needs its own image, such as a photo of the blue version, add the URL to the Variant image URL column on that variant’s row.

A few limits decide whether images import cleanly:

• Image count: up to 250 images per product.
• Alt text: up to 512 characters, though 125 or fewer works best.
• Filenames: the filename in the URL becomes the final filename in Shopify, so rename files before hosting them. Filenames must not end in _thumb, _small or _medium.
• Media types: 3D models and videos can’t be imported through the CSV and must be added to the product separately.

Update existing products without overwriting good data

The safest way to bulk update products is to export your current catalog, edit that file and re-import it. The export gives you a backup and a base file that already uses the correct handles and column names, so Shopify can match each row to the right product.

1. Export your existing products from the Products page and keep an untouched copy as your backup.
2. Make a working copy and edit only the values you want to change.
3. Import the working copy with Overwrite products with matching handles selected.

Without overwrite, Shopify ignores rows whose handles already exist, so the update has no effect. With overwrite selected, values in your CSV replace the values in matching columns for every product whose handle appears in the file, and Shopify treats each cell literally:

• Blank cell: if a non-required column is included but a cell is empty, Shopify clears the stored value.
• Omitted column: if a column is absent from the file, Shopify leaves that field unchanged.
• Dependent column without its related columns: Shopify deletes data. For example, including SKU without the Option1 name and Option1 value columns deletes the variant option.

Trim your import file to the columns you are changing, plus Title, URL handle and any columns the changed fields depend on. A missing column protects existing data, while an empty cell in an included column deletes it.

Be careful when you edit option values. Changing Option1 value data deletes the existing variant IDs and creates new ones, so apps, feeds or integrations that identify variants by ID can lose track of them. Check those dependencies before renaming sizes, colors or other option values in bulk.

A CSV cannot bulk delete products; use the bulk actions on the Products page instead. It also cannot bulk update product availability on other sales channels.

Optional columns: metafields, collections and market prices

Add these columns only when your upload must also set custom product data, collection membership or market-specific pricing. Each one has conditions that limit what it can do.

Product metafields

Metafields are custom fields that store extra product information, such as material or care instructions. The CSV can import a product metafield only after it is defined in your store. Find its namespace and key under Settings > Custom data > Products, then use either Fabric (product.metafields.custom.fabric) or product.metafields.custom.fabric as the column header, where custom is the namespace and fabric is the key.

The product CSV does not support variant metafields. To set values for each variant, use the variant bulk editor after the import.

Collection

A Collection column can go anywhere in the file and assigns each product to one collection, with a name of up to 255 characters. If the collection doesn’t exist, Shopify creates it. Conditional collections still follow their own rules, so a product joins one only when it meets that collection’s conditions.

Product exports do not include this column, so keep a separate record of the collection assignments you upload.

Market prices

If you use Shopify Markets, exports include Included / [Market], Price / [Market] and Compare At Price / [Market] columns. They appear only for markets with a single active catalog that isn’t shared with another market, so export your products first to see which columns your store supports. A fixed compare-at price for a market also requires a fixed price for that market.

Fix errors and check results

When a file has a problem, Shopify shows an error message in the review step. Most errors come from three causes:

• Missing mandatory fields: a row lacks a required value, such as Title for a new product or Title and URL handle for an update.
• Data in the wrong format: a value doesn’t match what its column accepts. Keep formatting consistent across the file, such as the same number of decimal places in every price and a single date format.
• Duplicate handles: two separate products share a URL handle. Give each distinct product its own handle.

Image problems are harder to spot because the product can still import. If an image URL is missing, misspelled, password-protected or otherwise not public, Shopify can’t download the file and the product ends up without that image. Correct the URL or rehost the image in Content > Files.

Fix the file and import it again rather than correcting products one by one, but watch the overwrite setting on the second pass. Products that imported the first time now exist, so with overwrite off your corrections to them won’t apply, and with overwrite on their rows replace existing data, including blank cells. Either remove rows that already imported correctly, or turn overwrite on and make sure every included column holds the values you want.

After the import finishes, check a sample of products in the admin:

• Images: the expected images appear in the right order, and variant images are attached to the correct variants.
• Descriptions: the text appears on the right products and displays as intended.
• Prices: prices and compare-at prices match your file, with the correct decimals.
• Variant counts: each product has the expected number of variants. If one is missing, check the handle and option values on its row first.

When the native CSV import is not enough

The native import works well for occasional uploads that a person prepares and checks by hand. Its fixed limits are:

• Every import is manual: you upload and confirm the file yourself each time.
• No scheduling: a weekly supplier update means repeating the full process every week.
• Single-location inventory only: multi-location quantities still need the separate inventory CSV.
• No variant metafields: these must be edited in the variant bulk editor.
• CSV files only: spreadsheets must be saved or exported to CSV before upload.

A dedicated import tool may be worth considering if your workflow keeps running into these limits:

• Recurring supplier files: some tools connect to file storage, map a supplier’s columns to Shopify’s and run imports on a schedule.
• Spreadsheet or XLSX workflows: if people edit product data by hand, some tools accept XLSX or Google Sheets directly, removing the conversion step.
• Per-row result reporting: some tools return a results file that marks each product as succeeded or failed with the error message, so you can re-import only the failures.
• Large catalogs: if your catalog may approach Shopify’s platform limits, check those limits in Shopify’s documentation before planning a single large import.

If none of these apply, the native import is usually enough.

Conclusion

A Shopify bulk upload usually succeeds or fails because of the CSV file and the overwrite setting, not the import itself. With a correctly structured file, a saved backup and a small test run, you can create and update large parts of your catalog quickly and safely. We hope this guide helps you get your next Shopify bulk upload right the first time.