A product CSV is a catalog mutation plan. Prepare complete handle groups, protect option and image relationships, test a small import, and verify the destination before scaling up.
Shopify's current product CSV guidance uses headers such as URL handle, Product image URL, Option1 name, and Option1 value. Older exports and troubleshooting examples can contain legacy names such as Handle, Image Src, Variant SKU, and Option1 Name. Do not rename a few columns and assume the rest are compatible. A file that mixes both families is a hybrid and needs deliberate review.
Export a fresh reference from the destination store when possible, or compare your headers with Shopify's current product CSV documentation. Keep the header order stable while investigating. Duplicate or blank headers can make later evidence ambiguous, and a generic header cleaner cannot decide which Shopify field a business column means.
The private Shopify product CSV validator detects current, legacy, and hybrid signatures. Its optional safe fixes cover case and outer whitespace only. It never guesses that an unknown field should become a price, SKU, option, image, market, or metafield column.
Shopify imports change a catalog. They are not a read-only preview, and Shopify says a product import cannot be canceled after it starts. Export the existing products before any overwrite operation, preserve that file outside the working directory, and record which store and market configuration it came from.
Choose whether the file creates new products or overwrites products with matching handles. In overwrite mode, blank cells can blank existing values. Missing option columns can remove variants, while changing option values can create new variant identities and disrupt dependencies. Treat a handle as catalog identity, not merely a convenient slug.
Write down the expected product count, variant count, publication behavior, inventory ownership, and rollback owner before importing. The preflight adds an explicit overwrite warning, but it cannot know which handles already exist or whether a blank cell is intentional.
Shopify documents a 15 MB product CSV file limit and expects UTF-8 text with LF-style line feeds. Use one header row, consistent field counts, and standard CSV quoting: quote values containing commas, quotes, or line breaks and double embedded quotes. Do not add decorative titles, subtotal rows, comments, or spreadsheet formatting.
A handle should use letters, numbers, and hyphens without spaces. Every product row needs the correct handle, and the first row in a product group carries the product-level title and other shared fields. Keep rows for the same handle together. Sorting only part of a sheet can detach image or variant rows from their product.
Open CSV files as raw UTF-8 when checking encoding. A spreadsheet may display replacement characters without making the corruption obvious. Excel workbooks do not expose original CSV bytes or line endings, so exporting a workbook to CSV is a separate step that must be reviewed.
Shopify supports up to three option sets. Each populated option value needs its matching option name, option levels must not skip, and each variant combination within a handle should be unique. A size value without a size name is incomplete; two rows with the same color-size combination compete for the same variant meaning.
A simple product often uses Title and Default Title as its first option pair. Products with real choices may use Color, Size, Material, or linked category attributes. Preserve the exact option structure when updating a catalog because option edits can create new variant records rather than updating the old ones.
Review SKU and barcode strategy separately from option uniqueness. The local tool can flag repeated option signatures and invalid field shapes, but it does not assume SKUs are globally unique, verify barcodes, resolve linked category data, or look up existing variant IDs.
Prices, compare-at prices, costs, quantities, weights, and image positions should be valid nonnegative numbers where the field requires them. A compare-at price is meaningful only in relation to price, but business and market rules still require review. Boolean, status, inventory policy, tracker, weight-unit, and fulfillment values must use the tokens supported by the chosen template.
Inventory fields form a dependency chain. Quantity and continue-selling behavior are not independent of the inventory tracker, and a fulfillment handle must exist in the destination store. The validator checks local combinations and documented syntax; it cannot query locations, inventory services, tax settings, shipping profiles, or fulfillment permissions.
For dynamic market columns and product metafields, keep the header structure exact and validate the definitions in Shopify. A syntactically plausible column can still reference a market, taxonomy field, or metafield definition that the destination store does not have.
Product and variant images use public HTTPS URLs that Shopify can download. Check that each URL is intentionally public, stable, and permitted for reuse. The validator checks HTTPS syntax only; it never fetches a URL, so it cannot confirm redirects, authentication, media type, dimensions, rate limits, or availability.
Image position should be a positive integer within its product group. Image-only rows still need the handle that attaches them to a product. Preserve group order while editing and avoid sorting a single column. Alt text can be up to 512 characters, while concise descriptions around 125 characters are more useful for many assistive and search contexts.
Review SEO title and description lengths as editorial limits, not automatic quality scores. The local checks use 70 characters for SEO title and 320 for SEO description. Collections and tags also have structural limits, but assigning the correct taxonomy remains a human decision.
Run the complete file through the validator and resolve every blocker. Review warnings even when export buttons become available. The normalized file changes only safe reviewed headers, quoting, UTF-8 serialization, and LF record endings; it preserves cell strings and row order.
Download the small-test CSV and inspect it before upload. It contains the first five distinct handles plus every row belonging to them, which protects variant and image relationships. Five products can still be too many for a high-risk overwrite, so reduce the test manually if one product has many variants or valuable existing state.
Follow Shopify's official product import steps, inspect the preview and warnings, and confirm the destination store. Do not use a preflight result as permission to ignore Shopify's own import preview.
After the small test, open every imported product. Check handle, title, description, vendor, category, type, tags, status, publication, options, variants, SKU, barcode, price, compare-at price, inventory, weight, shipping, tax, fulfillment, images, alt text, SEO fields, collection, markets, and metafields that matter to the workflow.
Compare the imported product and variant counts with the written expectation. Open storefront and admin views, test a representative variant selection, and confirm images appear on the correct product. For overwrite work, compare previously populated fields specifically so unintended blanks are caught.
If Shopify reports an error, use its common product CSV import issues as the first troubleshooting reference. Fix the smallest understood cause, regenerate a small test, and repeat. Preserve the rejected file, accepted test, backup export, and aggregate preflight report as an audit trail.
Yes. This local preflight checks file size, template family, headers, row width, handle groups, options, variants, inventory fields, image URL syntax, SEO lengths, and other documented structural rules. It cannot query your store or guarantee Shopify acceptance.
No. Parsing, findings, masked previews, normalization, the small-test copy, and reports stay in the browser tab. Image URLs are checked as text and are never fetched.
Yes. It detects current documented headers, legacy export headers, and unsafe hybrids. Safe fixes are limited to unambiguous case or outer-whitespace corrections.
Blank cells can replace existing product values when overwrite is selected. Option changes can create new variant identities, and missing option columns can remove variants. Back up products and test a small import first.
It contains the first five distinct product handles and every row belonging to those handles, including image-only and variant rows. It is still sensitive product data.
No. It checks supported header structure and HTTPS URL syntax without making requests. It cannot verify reachability, media type, taxonomy, store references, metafield definitions, or permissions.
It uses UTF-8 text, RFC-style CSV quoting, and LF record endings. It preserves source row order and cell strings and changes only reviewed safe headers.
No. A preflight covers local evidence only. Use a backup, import a small complete product group, inspect products and variants in Shopify, and only then expand the import.