Specification

The Shopify product CSV is a cross-row grammar, not a table.

It looks like a spreadsheet and it is not one. Meaning is carried between rows, and most of the ways it destroys a catalogue produce no error message at all. This is the whole rule set, with the evidence behind each one.

The structural model

A Shopify product CSV is not rows of products. It is a flat serialisation of a three-level tree — the file holds handle groups, each handle group is one product, and each product has both variants and images.

Because variants and images are lists of different lengths, the serialisation pads. A product with 2 variants and 9 images occupies 9 rows. Rows three to nine are neither products nor variants. They are image rows, and almost every rule that applies to a variant row is wrong about them.

So the single most important thing in this document is that a row has a role, and which rules apply depends on the role. This is not a nicety. Applying one option rule to every row of a real 590-row export fires 523 times, of which 519 are image-only rows and therefore false alarms — a report that is 99.2% noise. A merchant who scrolls past five hundred wrong answers will not read the right one.

One more distinction that the first draft of this document got backwards, and that cost us a wrong rule: option names are product-scoped and option values are variant-scoped. Option1 Name is declared once, on the product row; each variant row carries its own Option1 Value. Requiring the name on every variant row reported 200 blockers on a 204-row file that Shopify imports without complaint.

And what groups a product is the handle, and only the handle. Not the title, not the SKU, not position in the file. Two rows sharing a handle are the same product even if their titles differ and even if they are a hundred rows apart — which is the mechanism behind the most destructive rule below.

The three row roles

Product row
The first row of a handle group. Carries Title, Body, Vendor, Tags, Published and the SEO fields. Almost always also a variant row.
Variant row
Any row bearing variant-scoped data — SKU, price, weight, barcode, or an option value. Carries the option combination and its price and stock.
Image-only row
Handle plus Image Src, everything else blank. One additional image, and nothing else.

Classify the row before applying a rule to it.

How to read a rule

Every rule carries a severity and the evidence it rests on, and the second one governs the first.

Severity

Blocker
The import fails, or succeeds while corrupting data. The second kind is worse, and it is why this product exists.
Warning
Imports cleanly, but is probably not what you intended.
Info
An observation. No action implied.

Evidence, and the cap it applies

A rule may only be a blocker on documentary or observed evidence. Anything resting on a third-party assertion, or on an Admin API probe, is capped at warning no matter what it declares.

A measurement may lower a severity and may never raise it. If the API rejects something, the importer might still accept it — the file never reaches that layer — so an observed rejection is not grounds for telling you your import will fail. If the API accepts something, we have caught ourselves crying wolf, and one false alarm costs the whole report its credibility.

The severities printed below are the effective ones, after that cap.

The current table

20 rules
11 blockers, 5 warnings, 4 info. All of them run on the free report.
21 files
Real supplier catalogues every rule change is re-run against, 5 to 614 columns wide.

Cross-row rules

These are the rules a per-row tool cannot see, because the thing they are about happens between rows. Every one of them is invisible to a spreadsheet and to a language model reading your file a chunk at a time.

SH-001Blocker

Every row must carry a Handle

Reported as Handle missing

Fix. Fill in the handle of the product the row belongs to. A blank handle does not inherit from the row above.

Stated by Shopify’s documentation

SH-004Blocker

Title appears only on the first row of a handle group

Reported as Title repeated on a continuation row

Fix. Clear Title, Body (HTML), Vendor and Tags on every row after the first row of a handle.

Stated by Shopify’s documentation

SH-005Blocker

A multi-variant product declares an option, and every variant gives it a value

Reported as Variants with no option to tell them apart

Fix. Put Option1 Name on the product row, and an Option1 Value on every variant row. A single-variant product may leave both blank; Shopify assigns "Default Title".

Stated by Shopify’s documentation

What this looks like when it happens to you: Re-importing a product deleted its variants, and nothing warned me

SH-034Blocker

Every variant row carries an inventory policy and a fulfillment service

Reported as Variant row missing inventory policy or fulfillment service

Fix. Put a Variant Inventory Policy ('deny' or 'continue') and a Variant Fulfillment Service ('manual', or your app's handle) on every variant row, including continuation rows.

Stated by Shopify’s documentation

What this looks like when it happens to you: Shopify: "Fulfillment service can't be blank" · Shopify: "Inventory policy is not included in the list" · Shopify said "Products Imported" and a product never arrived

SH-035Blocker

Every product row carries a Title

Reported as Product has no name

Fix. Put a Title on the first row of every handle group. Continuation rows must still leave it blank (SH-004).

Stated by Shopify’s documentation

SH-006Blocker

Option value combinations are unique within a handle

Reported as Duplicate variant option combination

Fix. Give each variant a distinct combination of option values, or remove the duplicate row.

Stated by Shopify’s documentation

SH-007Blocker

Option count is consistent within a handle

Reported as Variant gives the wrong number of option values

Fix. Give every variant a value for each option the product declares.

Stated by Shopify’s documentation

SH-008Warning

A continuation row must contribute something

Reported as Empty continuation row

Fix. Delete the row. It carries a handle and no data.

Stated by Shopify’s documentation

SH-009Warning

At most 250 images per product

Reported as More than 250 images on one product

Fix. Reduce the product to 250 images or fewer.

Stated by Shopify’s documentation

SH-010Warning

At most 250 tags per product

Reported as More than 250 tags on one product

Fix. Reduce the product to 250 tags or fewer.

Stated by Shopify’s documentation

File-level rules

Properties of the file rather than of any row in it. A file that fails one of these has no failing rows to point at, which is why a report that only counts bad rows will call it clean.

SH-021Info

LF line endings

Reported as Windows (CRLF) line endings

Fix. There is no automatic answer to this one — which of the two things you meant is a decision only you can make. We name it and stop.

Stated by Shopify’s documentation

What this looks like when it happens to you: Are Windows line endings (CRLF) breaking my Shopify import?

SH-022Blocker

Header spelling must match Shopify exactly

Reported as Header spelling does not match Shopify

Fix. Correct the header spelling, including capitalisation.

Stated by Shopify’s documentation

Field limits

Character budgets. Nothing else in the ecosystem counts these for you, and the family splits in a way worth knowing: one of them is a hard rejection and the others are display advice that no platform enforces. We measured which is which rather than assuming.

SH-030Info

SEO Title within 70 characters

Reported as SEO Title over 70 characters

Fix. Rewrite the title to fit. Do not simply cut it — a title truncated mid-word reads as broken.

Measured against a real store

SH-031Info

SEO Description within 320 characters

Reported as SEO Description over 320 characters

Fix. Rewrite the description to fit rather than truncating it mid-sentence.

Measured against a real store

SH-032Warning

Image Alt Text within 512 characters

Reported as Image Alt Text over 512 characters

Fix. Shorten the alt text. It describes the image for screen readers; it is not a keyword field.

Measured against a real store

SH-033Info

Image alt text is readable at a glance

Reported as Alt text longer than our 125-character recommendation

Fix. Aim for around 125 characters. Alt text is read aloud in one breath by a screen reader.

Third-party assertion only — not in Shopify’s docs

What this document is not

It is not Shopify’s documentation and it does not speak for them. It is our working model of a format, assembled from their documentation where that exists, from real supplier files where it does not, and from breaking a real store on purpose where neither answered.

It is not complete. Some rules we would like to have are not here because we cannot establish them honestly, and the methodology page names them. A specification that claims to be finished is making the same promise this whole product refuses to make.

And a platform can change its behaviour at any time. This is a maintenance commitment, not a finished artifact — which is one of the reasons we never claim your import is guaranteed to succeed.

Run these rules against your own file.

All 20 of them, free, with the rows named. No account, and the file is deleted in the same request that reads it.

Check a file free