CSV structure · verified 2 August 2026

How should a Shopify product CSV be encoded and quoted?

Save the file as UTF-8, use commas as field delimiters, and quote any field containing a comma, quotation mark, or line break. Every data row must resolve to the same number of fields as the header row. A spreadsheet can display a damaged file as a tidy table, so inspect the actual CSV structure before import.

Why does UTF-8 matter?

UTF-8 represents product names, accents, non-Latin scripts, symbols, and punctuation consistently. Shopify attributes unexpected or garbled characters to files that are not UTF-8. Re-saving already-corrupted text cannot reconstruct the original characters, so compare the working file with its source after conversion.

A byte-order mark at the start of a UTF-8 file is handled by many applications but can sometimes become part of the first header in poorly behaved exporters. CatalogVigil removes a leading UTF-8 byte-order mark for parsing and reports structural header problems without rewriting the source file.

How do commas and quotation marks work?

CSV is a structured text format, not simply “one comma equals one column.” A comma inside a description is content when the whole field is enclosed in quotation marks. A quotation mark inside a quoted field is represented by two quotation marks.

If an opening quote is never closed, the parser may consume the following lines as one field. If a descriptive comma is not quoted, one logical cell can become two columns and shift every field after it.

Why do some spreadsheets create semicolon-separated files?

Spreadsheet software can follow regional settings when exporting “CSV,” using semicolons because a comma is the local decimal separator. Shopify's product CSV format expects commas. Changing only the filename extension does not change the delimiter. Choose an explicit comma-separated UTF-8 export option, then verify the first few rows in a plain-text editor or a CSV-aware validator.

Decimal commas are also risky in price fields. Shopify price fields should contain plain numeric values in the expected decimal form, without currency symbols or thousands formatting. Automated replacement is unsafe because the same punctuation can mean a decimal separator in one locale and a thousands separator in another.

What does a row-width error mean?

The header determines how many fields each row should contain. A row with too many or too few parsed fields usually points to an unquoted comma, a stray quote, a damaged line break, or a manual edit that removed a delimiter. Repair the source cell, not the shifted cells after it.

1. Find the first row whose field count differs from the header.
2. Compare it with the same product in an untouched export.
3. Inspect description, tag, option, and image-alt fields for commas or quotation marks.
4. Correct the quotation at the original field boundary.
5. Re-parse and confirm that later rows are no longer displaced.

Can formulas in a spreadsheet be dangerous?

A value beginning with characters such as an equals sign can be interpreted as a formula when a CSV is opened in spreadsheet software. That risk exists even if Shopify would treat the same value as text. CatalogVigil flags formula-like cells and neutralises formula prefixes in its issue-report export. It does not silently change catalogue values in the corrected product CSV because a leading character might be intentional product text.

What is a safe spreadsheet workflow?

1. Keep the original Shopify export unchanged.
2. Import the file into the spreadsheet using UTF-8 and comma-delimited settings.
3. Force identifiers such as SKUs and barcodes to text so leading zeros are preserved.
4. Avoid automatic date, scientific-notation, and currency conversions.
5. Export explicitly as UTF-8 comma-separated CSV.
6. Compare the output headers and representative identifiers with the original.
7. Run a local structure check before uploading.

What can and cannot be repaired automatically?

CatalogVigil can safely serialise a parsed table as UTF-8, comma-separated text with consistent LF line endings. It can also preview narrow header and enum normalisations. It will not guess how to repair a fundamentally ambiguous broken row, recover characters lost before loading, or reinterpret locale-formatted prices. Those cases need comparison with the source data.

Primary sources: Shopify product CSV guidance and Shopify common import issues. CatalogVigil's parser behavior is documented in the validation methodology.