Shopify CSV column headers not recognized (template mismatch)
When Shopify’s product CSV importer “does not recognize” columns, the symptom is predictable: fields you edited never show up on the product, or they land in unexpected places. In nearly every case, the header row does not match what Shopify’s parser expects for your store and CSV type—even if a spreadsheet still displays neat columns.
Cross-check against Shopify’s reference under Using CSV files to import and export products, and prefer a CSV you just exported from your own shop over any template downloaded elsewhere.
Spaces and invisible characters
A header like Variant SKU with a trailing space is a different header to the parser. The same applies to non-breaking spaces pasted from the web. CSV is literal text; spreadsheets hide those differences.
Renamed or “friendly” headers
Blog posts sometimes rename columns for readability. Shopify’s importer is not guessing—it maps exact names. If you want a human-readable mapping layer, keep it in documentation, not in row one of the file you upload.
Outdated templates
Products CSVs evolve as Shopify adds features (Metafields, localized fields in some flows, and plan-gated columns). An export from 2022 or a template from a random vendor may miss columns your current process requires—or include headers your shop no longer accepts.
Fix workflow
- Export one representative product from Shopify including all fields you rely on.
- Copy the header row verbatim into your working file.
- Merge your data into those columns without renaming the header cells.
- Import a two-row smoke test (header + one product) before running the full catalog.
When data exists but “wrong”
Misalignment can look like an encoding issue. If columns shifted, verify quoting first (UTF-8 and quoting), then return to headers.
FAQ
Can I reorder columns?
Usually yes if headers remain correct—Shopify maps by name, not position. Still, keep the export order when automating to reduce human error.
Why did only some rows fail?
Rows with values in unrecognized columns still parse; the columns are ignored. The failure looks like missing data rather than a hard error.
Do merged cells survive export from Excel?
No. Merged header cells break CSV structure. Never merge cells in the header row of a Shopify CSV.