Guide

Why a product CSV fails to import

Almost always one of six things, and the error message rarely names any of them. The worst ones are not mistakes you made in the file. They are changes your spreadsheet made on the way out.

1. Excel edited your data on the way in

This is the one that costs people an afternoon, because the file looks right until you look closely. Open a CSV in Excel or Google Sheets and it guesses a type for every cell, silently:

Every one of those is a sku that no longer matches the sku in your shop, which means an importer either creates a duplicate or fails to find the product it was meant to update. Nothing warns you.

The fix is to stop the guess rather than repair it afterwards. In Excel, use Data then From Text/CSV and set the sku column to Text before it loads. In Google Sheets, File then Import, and turn off Convert text to numbers and dates. Opening the file by double-clicking it is what skips the dialog and does the damage.

2. A comma inside a field, unquoted

A CSV separates columns with commas, so a comma inside a value has to sit inside quotes: "Blue mug, large". Without them, that one cell becomes two, and every column after it shifts one to the left. The row arrives with the description in the price field and the last column empty.

Any spreadsheet exporting to CSV quotes these correctly. Files assembled by hand, or by a script somebody wrote in a hurry, are where this shows up. Tags are the usual casualty, since they are already a comma-separated list living inside one cell.

3. Cells that start with = + @ or a tab

Those are read as formulas the moment the file opens in a spreadsheet, so a product called + Size Tee arrives as #NAME?. The usual advice is to put an apostrophe in front. Do not: the apostrophe travels into the importer as part of the value and ends up in the live listing. Fix the source row.

4. Curly quotes

Write your descriptions in Word or Google Docs and paste them across, and the quote marks will not be quote marks. Autocorrect turns them into typographic ones, which look almost identical and are a different character entirely. A parser looking for " does not recognise “, so it stops treating the field as quoted, and you are back to problem two.

The same autocorrect turns a hyphen into an en dash and three dots into an ellipsis character. Those are harmless in a description and fatal in a sku.

5. The file is not UTF-8

Save a CSV as Windows-1252 or Latin-1, which some versions of Excel still offer, and every accented character breaks. Café arrives as Café, and a curly quote arrives as three characters of rubbish. Export as CSV UTF-8 and it stays intact.

The opposite problem is the byte order mark, a few invisible bytes some tools put at the very start of a UTF-8 file. It attaches itself to your first column heading, so a header that looks exactly like sku does not match sku, and the importer reports a missing column that is plainly there. If a header is being rejected and you cannot see why, this is usually it.

6. Rows with the wrong number of columns

Every row needs the same number of fields as the header. A blank line in the middle, a stray comma at the end of one row, or a description with a line break in it that was never quoted will all produce a row that does not line up. Most importers refuse the whole file rather than the row, so one bad line stops two hundred good ones.

Before you upload anything

listWright refuses a cell that begins with =, +, @ or a tab rather than escaping it, for the reason in point three, and it checks tags and titles against Etsy's limits before anything comes back to you. A file in, a file out. If a CSV is the part you are stuck on, you can skip it: type your products in, or connect your Etsy shop and import the listings you already have.

Related

The columns listWright reads are on the help page. If you are trying to send the finished CSV to Etsy directly, that is not something Etsy supports, and it is worth knowing before you build a file for it. The tag rules that catch most people are on the tags page.