Shopify product CSV requirements
A summary of Shopify's official rules for product CSV files, and the checks this validator runs for each one. Last checked against Shopify's help center on October 29, 2026. Shopify's own documentation always takes precedence.
File format
Save as UTF-8
Shopify only reads UTF-8 files. Other encodings turn accented letters, curly quotes, and non-Latin text into symbols or cause “Illegal quoting” errors.
Separate columns with commas
Each column must be separated by a comma. Some Excel versions export with semicolons, which Shopify can't read.
Use straight quotes
Values that contain commas must be wrapped in straight quotes ("). Curly quotes or a missing quote break the row.
15 MB per file
A product CSV can't be larger than 15 MB. Split larger catalogs into several files.
Don't sort the file
Sorting in a spreadsheet can separate variants and images from their product. Importing a sorted file can overwrite products with bad data that can't be recovered.
Headers and required columns
Headers on the first line
The first line must contain the column headers exactly as listed in Shopify's column reference.
Headers are case-sensitive
Write headers exactly as Shopify does. For example, Handle works but handle doesn't. Extra spaces also cause errors.
Only official columns
You can't add your own columns. The only extra column allowed is Collection.
Old and new column names
Shopify still accepts column names from the old template, such as Variant Price, but recommends the current names, such as Price.
Required columns
New products need only Title. Products with variants, and updates to existing products, also need URL handle.
Variant data needs option columns
If you include variant columns such as SKU or weight, also include Option1 name and Option1 value. Otherwise existing variants are deleted and a default variant is created.
Barcode or Barcodes, not both
A file can't contain both the old Barcode column and the new Barcodes column. A file with both fails to import.
Metafield and market columns
Metafield columns use “Name (product.metafields.namespace.key)”. Market columns use “Price / Market name”, “Compare-at price / Market name”, and “Included / Market name”.
Row structure
| Row type | URL handle | Title | Option1 name | Option1 value | SKU | Price | Product image URL | Image position |
|---|---|---|---|---|---|---|---|---|
| Product | linen-shirt | Linen shirt | Size | S | LS-S | 39.00 | https://…/front.jpg | 1 |
| Variant | linen-shirt | M | LS-M | 39.00 | ||||
| Image | linen-shirt | https://…/back.jpg | 2 |
First row: the product
The first row of a product holds all product details, the first variant, and the first image.
Next rows: variants
Each extra variant gets its own row with the same URL handle. Leave Title, Description, Vendor, and Tags blank on these rows.
Image rows
Each extra image gets its own row with only the URL handle and the image details.
One product per handle
If the same handle starts a second product in the file, Shopify ignores it. A handle with no Title row is ignored too.
Column reference
| Column | Old name | Requirement | Allowed values or limit |
|---|---|---|---|
| TitleShopify's guide | — | Required. The product name shown to customers. Only fill it in on the product's first row. | |
| URL handleShopify's guide | Handle | Unique product ID used in the URL. Letters, numbers, and dashes only, no spaces. Repeat it on every row of the product. | |
| DescriptionShopify's guide | Body (HTML) | Product description. HTML is allowed. | |
| VendorShopify's guide | — | Brand or supplier name. | |
| Product categoryShopify's guide | Product Category, Standardized Product Type | Must match Shopify's Standard Product Taxonomy, as a full path or a category ID. | |
| TypeShopify's guide | Custom Product Type | Your own product type for organizing products. Any text. | |
| TagsShopify's guide | — | Separate tags with commas. Use letters, numbers, and hyphens. | Up to 250 tags |
| Published on online storeShopify's guide | Published | Whether the product is visible on the online store. Defaults to true. | truefalse |
| StatusShopify's guide | — | If the column is present, every product needs a value. Defaults to active when the column is missing. | activedraftarchived |
| SKUShopify's guide | Variant SKU | Variant SKU. Required when the variant uses a custom fulfillment service. | |
| Variant BarcodesShopify's guide | Barcodes, Variant Barcode, Barcode | Separate several barcodes with semicolons. Optional type prefix such as gtin: or upc:. | Up to 20 barcodes |
| Option1 nameShopify's guide | Option1 Name | Option name such as Size. Use Title for a product without variants. | Up to 3 options |
| Option1 valueShopify's guide | Option1 Value | Option value for this variant. Use Default Title for a product without variants. | |
| Option1 Linked ToShopify's guide | Option1 LinkedTo | Links the option to a category metafield: product.metafields.shopify.attribute-handle. | |
| Option2 nameShopify's guide | Option2 Name | Second option name. | |
| Option2 valueShopify's guide | Option2 Value | Second option value for this variant. | |
| Option2 Linked ToShopify's guide | Option2 LinkedTo | Category metafield link for the second option. | |
| Option3 nameShopify's guide | Option3 Name | Third option name. | |
| Option3 valueShopify's guide | Option3 Value | Third option value for this variant. | |
| Option3 Linked ToShopify's guide | Option3 LinkedTo | Category metafield link for the third option. | |
| PriceShopify's guide | Variant Price | Amount only, without currency symbols, such as 9.99. Defaults to 0.00. | |
| Compare-at priceShopify's guide | Variant Compare At Price, Variant Compare-at Price | Original price shown as crossed out. Should be higher than Price. | |
| Cost per itemShopify's guide | — | What the variant costs you. Amount only. | |
| Charge taxShopify's guide | Variant Taxable | Whether tax is charged on the variant. Defaults to true. | truefalse |
| Tax codeShopify's guide | Variant Tax Code | Tax code for tax services. Leave blank if you don't use one. | |
| Unit price total measureShopify's guide | Unit Price Total Measure | Total amount of the product, used to show unit prices. | |
| Unit price total measure unitShopify's guide | Unit Price Total Measure Unit | Unit of the total measure. | |
| Unit price base measureShopify's guide | Unit Price Base Measure | Base amount for the unit price, such as 100. | |
| Unit price base measure unitShopify's guide | Unit Price Base Measure Unit | Unit of the base measure. | |
| Inventory trackerShopify's guide | Variant Inventory Tracker | Which service tracks inventory. Leave blank if inventory isn't tracked. | shopifyshipwireamazon_marketplace_web |
| Inventory quantityShopify's guide | Variant Inventory Qty | Whole number. Only for stores with one location. Defaults to 0. | |
| Continue selling when out of stockShopify's guide | Variant Inventory Policy | Whether customers can buy when out of stock. Defaults to deny. | denycontinue |
| Weight value (grams)Shopify's guide | Variant Grams | Whole number of grams, without units or decimals. | |
| Weight unit for displayShopify's guide | Variant Weight Unit | Unit used to display the weight. Defaults to kg. | gkglboz |
| Requires shippingShopify's guide | Variant Requires Shipping | Whether the product is shipped. Defaults to true. | truefalse |
| Fulfillment serviceShopify's guide | Variant Fulfillment Service | Defaults to manual. Custom services use lowercase letters and dashes. | |
| Product image URLShopify's guide | Image Src | Public image link that starts with http:// or https://. One image per row. | Up to 250 images per product |
| Image positionShopify's guide | Image Position | Display order of the image, starting from 1. | |
| Image alt textShopify's guide | Image Alt Text | Short description of the image for screen readers and search engines. | Up to 512 characters |
| Variant image URLShopify's guide | Variant Image | Image shown when this variant is selected. | |
| Gift cardShopify's guide | Gift Card | Marks the product as a gift card. Gift cards can't be created by CSV. | truefalse |
| SEO titleShopify's guide | SEO Title | Title shown in search results. Blank uses the product title. | Up to 70 characters |
| SEO descriptionShopify's guide | SEO Description | Description shown in search results. Blank uses the product description. | Up to 320 characters |
| Packed product lengthShopify's guide | — | Packed length. Fill in all four packed size columns or none. | |
| Packed product widthShopify's guide | — | Packed width. Fill in all four packed size columns or none. | |
| Packed product heightShopify's guide | — | Packed height. Fill in all four packed size columns or none. | |
| Packed product dimension unitShopify's guide | — | Unit for the packed size. | cmin |
| CollectionShopify's guide | — | Adds the product to one collection, created if it doesn't exist. The only extra column you can add. | Up to 255 characters |
Overwriting existing products
Blank cells clear data
When “Overwrite products with matching handles” is on, a blank cell in an included column clears that value in your store.
Missing columns stay unchanged
Columns that aren't in the file keep their current values.
Changing option values recreates variants
Changing Option1, Option2, or Option3 values deletes the existing variant IDs and creates new ones, which can break apps that rely on them.
Shopify import errors explained
| Shopify error | What it means | Related checks |
|---|---|---|
| Ignored line #-## because handle example already exists | The handle starts another product that already appeared in the file. | PRODUCT_HANDLE_DUPLICATE |
| Ignored line #-## because it did not contain product data | A handle has rows, but none of them has a Title. | PRODUCT_TITLE_MISSINGPRODUCT_ROW_UNASSIGNED |
| Illegal quoting on line | The file isn't UTF-8, or a quote is in the wrong place. | FILE_ENCODING_NOT_UTF8FILE_QUOTE_MALFORMED |
| Missing or stray quote on line | A quote is missing or extra, often because of curly quotes. | FILE_QUOTE_MALFORMEDFILE_SMART_QUOTES |
| Invalid CSV header: missing headers | A required column is missing or a header is misspelled. | HEADER_TITLE_MISSINGHEADER_HANDLE_MISSINGHEADER_UNKNOWN |
| Network error: Unexpected token < in JSON at position 0 | A header doesn't exactly match Shopify's spelling, including uppercase and lowercase. | HEADER_CASE_MISMATCHHEADER_WHITESPACE |
| Inventory policy is not included in the list | Continue selling when out of stock isn't deny or continue. | INVENTORY_POLICY_INVALID |
| Inventory quantity can't be blank | Inventory is tracked but the quantity is blank. | INVENTORY_QTY_BLANK |
| Inventory quantity is not a number | The inventory quantity isn't a whole number. | INVENTORY_QTY_INVALID |
| Fulfillment service can't be blank | The fulfillment service is blank. | FULFILLMENT_BLANK |
| Validation failed: options are not unique | Two variants of a product have the same option values. | VARIANT_DUPLICATE_OPTIONS |
| Validation failed: price can't be blank | A variant has no price. | PRICE_BLANK |
| Validation failed: getaddrinfo: nodename nor servname provided, or not known | An image URL is incomplete or doesn't start with http. | IMAGE_URL_INVALIDIMAGE_URL_LOCAL |
| Not a valid product category | The product category doesn't match Shopify's taxonomy. | PRODUCT_CATEGORY_FORMAT |
All checks
File and encoding
- ErrorFile is emptyFILE_EMPTY
Export your products from Shopify again, or add at least one product row under the header.
Shopify's guide - ErrorFile is larger than 15 MBFILE_TOO_LARGE
Split the file into several smaller files and import them one at a time.
Shopify's guide - ErrorFile isn't saved as UTF-8FILE_ENCODING_NOT_UTF8
Open the file and save it again as “CSV UTF-8”. Google Sheets uses UTF-8 by default.
Shopify's guide - ErrorFile is saved as UTF-16FILE_ENCODING_UTF16
Save the file again as “CSV UTF-8 (comma delimited)” instead of “Unicode text”.
Shopify's guide - ErrorColumns aren't separated by commasFILE_DELIMITER_NOT_COMMA
Change your spreadsheet's export settings to use commas, or export from Google Sheets.
Shopify's guide - ErrorMissing or stray quoteFILE_QUOTE_MALFORMED
Open the row in a text editor and remove the extra quote, or wrap the whole value in straight quotes.
Shopify's guide - ErrorCurly quotes around a valueFILE_SMART_QUOTES
Replace curly quotes with straight quotes (").
Shopify's guide - ErrorWrong number of columnsFILE_ROW_FIELD_COUNT
Check for missing or extra commas in this row.
Shopify's guide - InfoBlank rowsFILE_BLANK_ROWS
Delete the blank rows. They don't affect the import, but make the file harder to review.
Shopify's guide
Headers
- ErrorTitle column is missingHEADER_TITLE_MISSING
Add a Title column with the product name on each product's first row.
Shopify's guide - ErrorURL handle column is missingHEADER_HANDLE_MISSING
Add a URL handle column and repeat the product's handle on every variant and image row.
Shopify's guide - ErrorColumn name has the wrong caseHEADER_CASE_MISMATCH
Rename the column to match the official spelling exactly.
Shopify's guide - ErrorExtra spaces in a column nameHEADER_WHITESPACE
Remove the spaces from the column name.
Shopify's guide - ErrorUnrecognized columnHEADER_UNKNOWN
Delete the column or rename it to an official column. Collection is the only extra column you can add.
Shopify's guide - ErrorDuplicate columnHEADER_DUPLICATE
Keep one of them and delete the others.
Shopify's guide - ErrorOld and new barcode columns togetherHEADER_BARCODE_CONFLICT
Keep only the Barcodes column.
Shopify's guide - WarningOld and new column names mixedHEADER_MIXED_FORMAT
Use the column names from one template. The new template is recommended.
Shopify's guide - WarningVariant columns without option columnsHEADER_OPTION_COLUMNS_MISSING
Add the Option1 name and Option1 value columns from your Shopify export.
Shopify's guide - ErrorPacked product columns incompleteHEADER_PACKED_PARTIAL
Include all four packed product columns, or none of them.
Shopify's guide - ErrorMetafield column name is invalidHEADER_METAFIELD_FORMAT
Use “Name (product.metafields.namespace.key)” or “product.metafields.namespace.key”.
Shopify's guide - InfoOld column namesHEADER_LEGACY_FORMAT
Consider switching to the current template for future compatibility.
Shopify's guide
Products
- ErrorProduct has no titlePRODUCT_TITLE_MISSING
Add the product name to the Title column on the product's first row.
Shopify's guide - ErrorRow doesn't belong to a productPRODUCT_ROW_UNASSIGNED
Add the product's URL handle to these rows, or delete them.
Shopify's guide - ErrorDuplicate product handlePRODUCT_HANDLE_DUPLICATE
Give each product its own handle, or merge the rows into one product.
Shopify's guide - ErrorHandle has invalid charactersPRODUCT_HANDLE_INVALID
Use only letters, numbers, and dashes.
Shopify's guide - WarningHandle has uppercase lettersPRODUCT_HANDLE_UPPERCASE
Use lowercase letters in the handle.
Shopify's guide - WarningProduct rows are split upPRODUCT_ROWS_NOT_CONTIGUOUS
Keep all rows of a product together, starting with the row that has the Title.
Shopify's guide - WarningProduct details differ between rowsPRODUCT_FIELD_CONFLICT
Leave product-level columns blank on variant and image rows, or make them match the first row.
Shopify's guide - ErrorInvalid statusPRODUCT_STATUS_INVALID
Use active, draft, or archived.
Shopify's guide - ErrorStatus is blankPRODUCT_STATUS_BLANK
Enter active, draft, or archived, or remove the Status column to make all products active.
Shopify's guide - ErrorInvalid true/false valuePRODUCT_BOOLEAN_INVALID
Use true or false.
Shopify's guide - ErrorToo many tagsPRODUCT_TAGS_TOO_MANY
Remove tags until there are 250 or fewer.
Shopify's guide - InfoTags with accents or symbolsPRODUCT_TAGS_CHARACTERS
Use letters, numbers, and hyphens in tags.
Shopify's guide - WarningProduct category formatPRODUCT_CATEGORY_FORMAT
Use the full category path such as “Apparel & Accessories > Clothing” or a category ID such as “aa-1”.
Shopify's guide - WarningGift card can't be created by CSVPRODUCT_GIFT_CARD_CREATE
Create the gift card in Shopify first, then use the CSV only to update its details.
Shopify's guide - ErrorCollection name too longPRODUCT_COLLECTION_TOO_LONG
Shorten the collection name.
Shopify's guide
Options and variants
- ErrorOption name is missingOPTION_NAME_MISSING
Add the option name (such as Size or Color) to the product's first row.
Shopify's guide - ErrorOption value is missingOPTION_VALUE_MISSING
Enter a value for every option on every variant row.
Shopify's guide - ErrorDuplicate option nameOPTION_NAME_DUPLICATE
Give each option a different name.
Shopify's guide - ErrorOption is skippedOPTION_GAP
Fill options in order: Option1 first, then Option2, then Option3.
Shopify's guide - ErrorDuplicate variantVARIANT_DUPLICATE_OPTIONS
Change one of the option values, or remove the duplicate row.
Shopify's guide - ErrorDefault Title used with several variantsVARIANT_DEFAULT_TITLE_MISUSE
Use a real option name such as Size, or keep only one variant.
Shopify's guide - WarningMany variantsVARIANT_COUNT_HIGH
Check that every variant is intended.
Shopify's guide - ErrorInvalid option linkVARIANT_LINKED_TO_FORMAT
Use product.metafields.shopify.attribute-handle, or leave the column blank.
Shopify's guide
Prices
- ErrorInvalid pricePRICE_INVALID
Use digits with a dot as the decimal separator, without currency symbols, such as 24.90.
Shopify's guide - ErrorNegative pricePRICE_NEGATIVE
Enter a price of 0 or more.
Shopify's guide - WarningPrice is blankPRICE_BLANK
Enter a price for every variant.
Shopify's guide - WarningPrice is zeroPRICE_ZERO
Check that the product is meant to be free.
Shopify's guide - WarningCompare-at price not higher than pricePRICE_COMPARE_AT_NOT_HIGHER
Make the compare-at price higher than the price, or leave it blank.
Shopify's guide - ErrorInvalid costPRICE_COST_INVALID
Use digits with a dot as the decimal separator, without currency symbols.
Shopify's guide - InfoCost higher than pricePRICE_COST_ABOVE_PRICE
Check the price and cost for this variant.
Shopify's guide - ErrorMarket compare-at price without pricePRICE_MARKET_COMPARE_WITHOUT_PRICE
Set a fixed price for the market, or remove its compare-at price.
Shopify's guide
Inventory and fulfillment
- ErrorInvalid inventory trackerINVENTORY_TRACKER_INVALID
Use shopify, shipwire, amazon_marketplace_web, or leave it blank if inventory isn't tracked.
Shopify's guide - ErrorInventory quantity isn't a whole numberINVENTORY_QTY_INVALID
Enter a whole number such as 12.
Shopify's guide - ErrorInventory quantity is blankINVENTORY_QTY_BLANK
Enter a quantity, or clear the Inventory tracker column if you don't track inventory.
Shopify's guide - ErrorInvalid out-of-stock policyINVENTORY_POLICY_INVALID
Use deny or continue.
Shopify's guide - ErrorOut-of-stock policy is blankINVENTORY_POLICY_BLANK
Enter deny or continue.
Shopify's guide - ErrorFulfillment service is blankFULFILLMENT_BLANK
Enter manual if you fulfill orders yourself.
Shopify's guide - ErrorInvalid fulfillment service nameFULFILLMENT_FORMAT
Use lowercase letters and dashes only, such as joans-fulfillment.
Shopify's guide - ErrorSKU required for fulfillment serviceFULFILLMENT_SKU_REQUIRED
Enter a SKU for every variant handled by a custom fulfillment service.
Shopify's guide
Shipping and weight
- ErrorInvalid weightWEIGHT_INVALID
Enter the weight in grams without units or decimals. For example, 5.125 kg is 5125.
Shopify's guide - ErrorInvalid weight unitWEIGHT_UNIT_INVALID
Use g, kg, lb, or oz.
Shopify's guide - ErrorInvalid true/false valueSHIPPING_BOOLEAN_INVALID
Use true or false.
Shopify's guide - ErrorPacked size incompletePACKED_PARTIAL
Fill in length, width, height, and unit, or leave all four blank.
Shopify's guide - ErrorInvalid packed size unitPACKED_UNIT_INVALID
Use cm or in.
Shopify's guide - ErrorInvalid packed sizePACKED_VALUE_INVALID
Enter a number greater than 0.
Shopify's guide - InfoWeight missing for shipped productWEIGHT_MISSING_PHYSICAL
Enter the weight if you use carrier-calculated shipping or a fulfillment service.
Shopify's guide
SKUs and barcodes
- WarningDuplicate SKUSKU_DUPLICATE
Give each variant its own SKU unless they share stock on purpose.
Shopify's guide - WarningSKU has extra spacesSKU_WHITESPACE
Remove the extra spaces and line breaks.
Shopify's guide - ErrorToo many barcodesBARCODE_TOO_MANY
Keep at most 20 barcodes, separated by semicolons.
Shopify's guide - WarningUnknown barcode typeBARCODE_TYPE_UNKNOWN
Use a type such as gtin, upc, ean, or isbn, or remove the prefix to import it as a custom barcode.
Shopify's guide - WarningBarcode needs escapingBARCODE_ESCAPE
Write \\ for a backslash, \; for a semicolon, and \: for a colon inside a barcode.
Shopify's guide - WarningInvalid GTIN check digitBARCODE_GTIN_CHECKSUM
Check the barcode for typos. Marketplaces such as Google Shopping reject invalid GTINs.
Shopify's guide - WarningDuplicate barcodeBARCODE_DUPLICATE
Each sellable item should have its own barcode.
Shopify's guide
Images
- ErrorInvalid image URLIMAGE_URL_INVALID
Use a public link that starts with https://.
Shopify's guide - InfoImage URL isn't HTTPSIMAGE_URL_NOT_HTTPS
Use an https:// link if the image host supports it.
Shopify's guide - ErrorImage URL isn't publicIMAGE_URL_LOCAL
Upload the image to Shopify Files or another public host and use that link.
Shopify's guide - WarningThumbnail image URLIMAGE_URL_SIZE_SUFFIX
Link to the full-size image instead.
Shopify's guide - ErrorInvalid image positionIMAGE_POSITION_INVALID
Enter 1 for the first image, 2 for the second, and so on.
Shopify's guide - WarningDuplicate image positionIMAGE_POSITION_DUPLICATE
Give each image of a product its own position.
Shopify's guide - ErrorToo many imagesIMAGE_COUNT_EXCEEDED
Remove images until there are 250 or fewer.
Shopify's guide - ErrorImage alt text too longIMAGE_ALT_TOO_LONG
Keep alt text short and descriptive, ideally under 125 characters.
Shopify's guide - InfoImage alt text missingIMAGE_ALT_MISSING
Add alt text to help screen reader users and search engines.
Shopify's guide - InfoVariant image not in product imagesIMAGE_VARIANT_NOT_IN_GALLERY
Use one of the product image URLs for the variant image.
Shopify's guide
SEO
- WarningSEO title too longSEO_TITLE_TOO_LONG
Shorten the SEO title so it isn't cut off in search results.
Shopify's guide - WarningSEO description too longSEO_DESCRIPTION_TOO_LONG
Shorten the SEO description.
Shopify's guide
Import risks
- WarningBlank column clears existing dataRISK_BLANK_COLUMN_CLEARS
Delete the column if you don't want to change it, or fill it in.
Shopify's guide - WarningVariants will be recreatedRISK_VARIANTS_RECREATED
Add the Option1 name and Option1 value columns from your Shopify export.
Shopify's guide - WarningFile may have been sortedRISK_SORTED_FILE
Re-export from Shopify, or restore the original row order before importing.
Shopify's guide - InfoInventory quantity is single-location onlyRISK_INVENTORY_MULTI_LOCATION
If your store has several locations, update inventory with the inventory CSV file instead.
Shopify's guide