Shopify CSV answer · verified 2 August 2026
Which Shopify product CSV headers are required?
For new products: Shopify says the Title column is required; URL handle is also required when variants are added. For updates: URL handle and Title are required. Variant-related columns can require Option1 name and Option1 value even when the two headline fields are present.
Why does create or update intent matter?
A new-product file can let Shopify derive a handle from a title for a simple product. An update needs the URL handle to identify the existing product. CatalogVigil asks for the intent before validation so it does not apply the wrong required-field rule.
Are older header names still accepted?
Shopify says it maintains backward compatibility with older column names but recommends the current format. CatalogVigil recognises common pairs and offers an optional rename:
| Legacy | Current |
|---|---|
| Handle | URL handle |
| Body (HTML) | Description |
| Published | Published on online store |
| Variant SKU | SKU |
| Variant Price | Price |
| Image Src | Product image URL |
| Variant Image | Variant image URL |
A file should not contain both a legacy header and its current equivalent unless you know exactly how the importer will resolve them. CatalogVigil treats a duplicate or ambiguous mapping as a problem instead of choosing one column silently.
Which groups of columns deserve separate review?
| Group | Examples | Main review question |
|---|---|---|
| Product identity | URL handle, Title | Does this row create a product or match the intended existing product? |
| Variant identity | Option names/values, SKU, Barcode | Is the complete option combination present and attached to the right product? |
| Commercial values | Price, Compare-at price | Are values plain numbers with no ambiguous currency formatting? |
| Content | Description, Vendor, Tags | Are commas, quotes, HTML, and blank update cells intentional? |
| Images | Product image URL, Variant image URL | Is the URL public and associated with the correct handle/variant? |
| Dynamic fields | Markets, Google Shopping, metafields | Does the header match the current store configuration and documented pattern? |
Can a product CSV contain custom columns?
Shopify documents Collection as the only ordinary extra column. Market columns vary by configured market, Google Shopping columns share a prefix, and product metafields use a documented namespace/key header pattern. Variant metafields are not supported in product CSV import/export.
Why can a valid header still be unsafe in an update?
A header can be correctly spelled while the cells below it are destructive. If an optional column is present with blank cells, Shopify can replace existing values with blank when an overwrite is performed. If the column is omitted entirely, the existing data is preserved. Build narrow update files and read the product update guide before carrying empty template columns into an import.
How should dynamic fields be checked?
Do not build a permanent universal template by copying every field ever seen. Export from the target store, because market columns and metafields can differ between stores. A product-metafield header must match Shopify's documented namespace/key and type pattern. Store-dependent existence and type compatibility still require Shopify's validation; a browser-local check can validate only the file's header shape.
What should I do next?
- Use a fresh Shopify export or official sample as the reference.
- Decide whether the file creates or updates products.
- Compare raw headers before editing any data.
- Remove unrelated optional columns from narrow update files.
- Preserve complete option dependencies and product row groups.
- Run CatalogVigil, resolve blockers, keep a backup, and review Shopify's own import preview before confirming an overwrite.
Primary source: Shopify Help Center: Using CSV files to import and export products. Independent summary; Shopify's current page controls.