What “Overwrite products with matching handles” does
When you import a product CSV, Shopify’s import dialog offers an option called Overwrite products with matching handles. A handle is the unique identifier in a product’s web address, for example black-sunglasses.
- Option selected: when a handle in your file matches an existing product, the values in your file replace the values in the matching columns of that product.
- Option not selected: products whose handle already exists are ignored, so nothing is updated. This is why an import that “worked” sometimes changes nothing at all.
Four ways a CSV update can remove data
1. A blank cell overwrites the existing value
If a column is in your file but a cell is empty, Shopify replaces the stored value with an empty one. Shopify’s own example: if a product has a vendor in your store and your file has a Vendor column with an empty cell, the vendor is cleared. Spreadsheet formulas that return an empty string can cause this without anyone noticing.
2. A column that isn’t in the file is left alone
If an optional column is missing from the file entirely, the existing values in your store stay as they are. That makes removing the columns you don’t intend to change the simplest protection, with the exception in the next point.
3. Variant columns without the Option columns can delete variants
Fields such as SKU, price, weight and inventory belong to a variant. Shopify’s documentation warns that if your file leaves out the Option1 name and Option1 value columns, a new default variant is created and the existing variants are deleted. This is the most damaging mistake, because a file containing only a handle, a title and a price column looks harmless.
4. Changing an option value creates new variant IDs
Shopify warns that changing data in the Option1, Option2 or Option3 value columns deletes the existing variant IDs and creates new ones. Apps and integrations that stored the old IDs, such as reviews, subscriptions, feed tools or an ERP, can lose the link. Treat even a small edit to option text as a real change.
A safer update workflow
- Export first. Shopify’s guidance is to export the products you want to change and edit that file. Save an untouched copy as well; it is your way back if something goes wrong.
- Decide which columns you are changing (prices, tags, SEO fields) and write them down before you open the file.
- Keep the identifying columns: Handle and Title are required when updating, and variant edits also need the Option name and value columns that your export contains.
- Remove other columns you don’t intend to change, except those that other columns depend on. If you are unsure whether a column is a dependency, keep it and leave its exported values untouched.
- Filter for blanks in important columns (Vendor, Type, Status, Price) before you import, so an accidental empty cell doesn’t clear real data.
- Test with two or three products first. This is our suggestion rather than a Shopify requirement, but it is the cheapest safeguard there is.
- Spot-check after importing: variant count, prices, inventory and images on a few products in the admin.
Which columns to keep for common edits
Shopify’s current documentation uses names such as URL handle, Option1 name and Price; older templates use Handle, Option1 Name and Variant Price. Shopify says it keeps backward compatibility with older names. Use whichever style your export uses, and avoid including the same field under both names.
| If you only want to change… | Keep these columns | Why |
|---|---|---|
| Prices | Handle, Title, Option1 Name, Option1 Value, Variant Price (plus any other Option name/value columns in your export) | Price is a variant-level field, so the Option columns must travel with it. |
| Tags | Handle, Title, Tags | Treat the Tags cell as a replacement for the product’s tags, not an addition to them. |
| SEO title and description | Handle, Title, SEO Title, SEO Description | Leave a cell empty only if you want the stored value cleared. |
| Stock (single-location stores) | Handle, Title, Option1 Name, Option1 Value, Variant Inventory Qty | Multi-location stores should use Shopify’s separate inventory CSV instead. |
What ShopiClean can and can’t do here
Disclosure: ShopiClean is our own product. Everything in this guide can be done by hand in a spreadsheet; the tool simply automates the checks. The scan and the on-screen 5-row preview are free, and downloading the repaired file needs a 7-Day Pass ($9).
What it does:
- Reads your file in the browser and flags a file that has variant columns (SKU, price or inventory) but no Option1 Name / Option1 Value columns, which is the situation described in point 3.
- Warns about variants with a blank or 0.00 price. This matters because a blank price either triggers an import error or imports as 0.00 (see our price and inventory format guide).
What it does not do:
- It can’t see your store, so it can’t tell you which products already exist, what an overwrite will change or which apps depend on variant IDs.
- It is not a substitute for exporting first and running a small test import.
Sources and how this guide was checked
The Shopify behaviors described above were checked against the Shopify Help Center pages below on 19 October 2026. Shopify can change how imports work, so if something here differs from what you see, trust Shopify’s documentation.