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.

Row structure

A product with two variants and two images
Row typeURL handleTitleOption1 nameOption1 valueSKUPriceProduct image URLImage position
Productlinen-shirtLinen shirtSizeSLS-S39.00https://…/front.jpg1
Variantlinen-shirtMLS-M39.00
Imagelinen-shirthttps://…/back.jpg2

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

ColumnOld nameRequirementAllowed 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 guideHandleUnique product ID used in the URL. Letters, numbers, and dashes only, no spaces. Repeat it on every row of the product.
DescriptionShopify's guideBody (HTML)Product description. HTML is allowed.
VendorShopify's guide—Brand or supplier name.
Product categoryShopify's guideProduct Category, Standardized Product TypeMust match Shopify's Standard Product Taxonomy, as a full path or a category ID.
TypeShopify's guideCustom Product TypeYour 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 guidePublishedWhether 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 guideVariant SKUVariant SKU. Required when the variant uses a custom fulfillment service.
Variant BarcodesShopify's guideBarcodes, Variant Barcode, BarcodeSeparate several barcodes with semicolons. Optional type prefix such as gtin: or upc:.Up to 20 barcodes
Option1 nameShopify's guideOption1 NameOption name such as Size. Use Title for a product without variants.Up to 3 options
Option1 valueShopify's guideOption1 ValueOption value for this variant. Use Default Title for a product without variants.
Option1 Linked ToShopify's guideOption1 LinkedToLinks the option to a category metafield: product.metafields.shopify.attribute-handle.
Option2 nameShopify's guideOption2 NameSecond option name.
Option2 valueShopify's guideOption2 ValueSecond option value for this variant.
Option2 Linked ToShopify's guideOption2 LinkedToCategory metafield link for the second option.
Option3 nameShopify's guideOption3 NameThird option name.
Option3 valueShopify's guideOption3 ValueThird option value for this variant.
Option3 Linked ToShopify's guideOption3 LinkedToCategory metafield link for the third option.
PriceShopify's guideVariant PriceAmount only, without currency symbols, such as 9.99. Defaults to 0.00.
Compare-at priceShopify's guideVariant Compare At Price, Variant Compare-at PriceOriginal 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 guideVariant TaxableWhether tax is charged on the variant. Defaults to true.truefalse
Tax codeShopify's guideVariant Tax CodeTax code for tax services. Leave blank if you don't use one.
Unit price total measureShopify's guideUnit Price Total MeasureTotal amount of the product, used to show unit prices.
Unit price total measure unitShopify's guideUnit Price Total Measure UnitUnit of the total measure.
Unit price base measureShopify's guideUnit Price Base MeasureBase amount for the unit price, such as 100.
Unit price base measure unitShopify's guideUnit Price Base Measure UnitUnit of the base measure.
Inventory trackerShopify's guideVariant Inventory TrackerWhich service tracks inventory. Leave blank if inventory isn't tracked.shopifyshipwireamazon_marketplace_web
Inventory quantityShopify's guideVariant Inventory QtyWhole number. Only for stores with one location. Defaults to 0.
Continue selling when out of stockShopify's guideVariant Inventory PolicyWhether customers can buy when out of stock. Defaults to deny.denycontinue
Weight value (grams)Shopify's guideVariant GramsWhole number of grams, without units or decimals.
Weight unit for displayShopify's guideVariant Weight UnitUnit used to display the weight. Defaults to kg.gkglboz
Requires shippingShopify's guideVariant Requires ShippingWhether the product is shipped. Defaults to true.truefalse
Fulfillment serviceShopify's guideVariant Fulfillment ServiceDefaults to manual. Custom services use lowercase letters and dashes.
Product image URLShopify's guideImage SrcPublic image link that starts with http:// or https://. One image per row.Up to 250 images per product
Image positionShopify's guideImage PositionDisplay order of the image, starting from 1.
Image alt textShopify's guideImage Alt TextShort description of the image for screen readers and search engines.Up to 512 characters
Variant image URLShopify's guideVariant ImageImage shown when this variant is selected.
Gift cardShopify's guideGift CardMarks the product as a gift card. Gift cards can't be created by CSV.truefalse
SEO titleShopify's guideSEO TitleTitle shown in search results. Blank uses the product title.Up to 70 characters
SEO descriptionShopify's guideSEO DescriptionDescription 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 errorWhat it meansRelated checks
Ignored line #-## because handle example already existsThe handle starts another product that already appeared in the file.PRODUCT_HANDLE_DUPLICATE
Ignored line #-## because it did not contain product dataA handle has rows, but none of them has a Title.PRODUCT_TITLE_MISSINGPRODUCT_ROW_UNASSIGNED
Illegal quoting on lineThe file isn't UTF-8, or a quote is in the wrong place.FILE_ENCODING_NOT_UTF8FILE_QUOTE_MALFORMED
Missing or stray quote on lineA quote is missing or extra, often because of curly quotes.FILE_QUOTE_MALFORMEDFILE_SMART_QUOTES
Invalid CSV header: missing headersA required column is missing or a header is misspelled.HEADER_TITLE_MISSINGHEADER_HANDLE_MISSINGHEADER_UNKNOWN
Network error: Unexpected token < in JSON at position 0A header doesn't exactly match Shopify's spelling, including uppercase and lowercase.HEADER_CASE_MISMATCHHEADER_WHITESPACE
Inventory policy is not included in the listContinue selling when out of stock isn't deny or continue.INVENTORY_POLICY_INVALID
Inventory quantity can't be blankInventory is tracked but the quantity is blank.INVENTORY_QTY_BLANK
Inventory quantity is not a numberThe inventory quantity isn't a whole number.INVENTORY_QTY_INVALID
Fulfillment service can't be blankThe fulfillment service is blank.FULFILLMENT_BLANK
Validation failed: options are not uniqueTwo variants of a product have the same option values.VARIANT_DUPLICATE_OPTIONS
Validation failed: price can't be blankA variant has no price.PRICE_BLANK
Validation failed: getaddrinfo: nodename nor servname provided, or not knownAn image URL is incomplete or doesn't start with http.IMAGE_URL_INVALIDIMAGE_URL_LOCAL
Not a valid product categoryThe product category doesn't match Shopify's taxonomy.PRODUCT_CATEGORY_FORMAT
Shopify's guide

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

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