All articles

Shopify Product CSV Format: Columns and What They Mean

November 19, 2026 · 8 min read

Learn which columns a Shopify product CSV requires, what each column means, accepted values and defaults, and which columns you can safely leave out.

The short list: required and optional columns

A Shopify product CSV needs very little. As of this writing, a file that creates new products needs only the Title column, and a file that adds variants also needs URL handle. Every other column is optional.

What you are doingColumns you must include
Creating products without variantsTitle
Creating products with variantsTitle and URL handle
Updating existing productsURL handle and Title

Some columns that Shopify needs internally get a default when you leave them out or blank. The defaults are listed below, next to each column. Shopify's page on using CSV files to import and export products is the reference for current names and limits, and column names do change, so check it before you build a large file.

File rules that apply to every column

  • Line 1 must be the header row, with one column name per cell.
  • Columns are separated by commas.
  • Save the file as UTF-8 with LF line endings.
  • Shopify's sample file has two example products. Delete them before you reuse the template.
  • The sample file has no Collection column. You can add one yourself if you want to assign collections on import.

Older names such as Handle, Body (HTML) and Variant SKU still work through backward compatibility, but Shopify recommends the current names. Use the names in this article, and compare your header row with Shopify's current template if anything looks different.

Product detail columns

These describe the product as a whole. On variant rows, leave Title, Description, Vendor and Tags empty and repeat only the URL handle.

Column (as of this writing)What it meansAccepted values and defaults
TitleThe product nameRequired for new products
URL handleThe product's web address ending, and the key that ties rows togetherRequired when adding variants or updating
DescriptionThe product descriptionText or HTML
VendorThe brand or supplier nameFree text
Product categoryShopify's product taxonomy categoryMust be a valid category
TypeYour own product type labelFree text
TagsSearch and filter labelsUp to 250 per product
CollectionThe collection to add the product to (import only)One collection per product, name up to 255 characters
Published on online storeWhether the product is visible on your online storetrue (default) or false
StatusWhether the product is liveactive (default), draft or archived
Gift cardMarks a product as a gift cardfalse (default) or true

Two details trip people up. First, if the Status column is present, every row needs a value in it. If the column is absent, products upload as active. Second, a column named Category is imported as Collection. Use Product category for the taxonomy.

You cannot create a gift card through CSV, so leave the Gift card column alone unless you are updating an existing file.

Variant and option columns

A variant is one purchasable version of a product, such as a size or color. These columns identify it.

  • Option1 name, Option1 value (and the same for Option2 and Option3): the option, such as Color, and this row's value, such as Black. A product can have up to three options.
  • SKU: your stock-keeping code for the variant.
  • Barcodes: one or more barcodes, separated by semicolons, up to 20 per product or variant. A file cannot contain both the old Barcode column and Barcodes.
  • Option LinkedTo columns: used to link an option to a metafield.

Here is how a product with two variants looks. The second row repeats the URL handle and leaves Title empty.

URL handleTitleOption1 nameOption1 valueSKUPrice
canvas-toteCanvas ToteColorNaturalTOTE-NAT24.00
canvas-toteColorBlackTOTE-BLK24.00

Each variant needs a unique combination of option values. Two rows with the same handle and the same values trigger a options are not unique error.

Pricing, inventory and shipping columns

ColumnWhat it meansAccepted values and defaults
PriceSelling priceNumber only, no currency symbol. Default 0.00
Price / InternationalPrice for international marketsNumber only
Compare-at priceThe original price shown crossed outNumber only
Compare-at price / InternationalSame, for international marketsNumber only
Cost per itemWhat the item costs youNumber only
Charge taxWhether tax appliestrue (default) or false
Inventory trackerWho tracks stockshopify, shipwire, amazon_marketplace_web, or blank for untracked
Inventory quantityUnits in stockDefault 0. Single-location stores only
Continue selling when out of stockAllow orders at zero stockdeny (default) or continue
Fulfillment serviceWho ships the itemmanual (default), shipwire, webgistix, amazon_marketplace_web, or a custom service handle in lowercase with dashes
Requires shippingWhether the item is physicaltrue (default) or false
Included / [Primary], Included / InternationalWhether the product is sold in each marketAppear on exports for some markets

If your store has more than one location, Inventory quantity in the product file is not the right tool. Shopify points multi-location stores to its separate inventory CSV.

Weight and packed size

Weight value (grams) is a whole number of grams with no unit. A 4 lb item is entered as 1814. The default is 0. Weight unit for display only changes how the weight is shown: g, kg (default), lb or oz.

The packed size columns are Packed product length, width, height and dimension unit (cm or in). Fill all four or leave all four blank, or the import errors.

Image, SEO and other optional columns

  • Product image URL: a public link to the image. Shopify fetches it during import, so a link that requires a login will fail.
  • Image position: the order of images. Use one extra row per additional image, repeating the URL handle. A product can have up to 250 images.
  • Image alt text: a description for accessibility. The maximum is 512 characters, and Shopify recommends 125 or fewer.
  • Variant image URL: the image tied to one variant.
  • SEO title (70 characters) and SEO description (320 characters): the text for search results.
  • Google Shopping columns, including Google Product Category: used for Google listings.
  • Product metafields: custom data. The header looks like Name (product.metafields.namespace.key) or just product.metafields.namespace.key. Variant metafields are not supported in CSV.

Rules that connect columns

Most import failures come from columns that depend on each other. Check these before you upload:

  • If Inventory tracker is shopify, Continue selling when out of stock and Fulfillment service cannot be blank.
  • Packed product length, width, height and unit are all filled or all blank.
  • The file has Barcodes, not both Barcodes and Barcode.
  • Every variant row repeats the exact same URL handle as its product. A mistyped handle creates a separate product.
  • No product has more than three options.

What happens to columns you leave out or leave blank

When you import with the overwrite option ticked, a column you include with a blank cell replaces the existing value with blank. A column you omit entirely leaves the existing values unchanged. So a Vendor column with empty cells will wipe vendors, but a file with no Vendor column will not touch them.

Two other behaviors matter for updates:

  • If you include variant columns such as SKU without Option1 name and Option1 value, Shopify creates a new default variant and deletes the existing variants.
  • Changing an option value creates new variant IDs.

If you do not tick overwrite, rows whose handle already exists are ignored. CSV import cannot bulk-delete products.

Errors that point back to columns

Shopify lists the common ones on its common import issues page. Several map directly to the columns above:

  • Invalid CSV header: missing headers: a header is renamed, has stray whitespace, or there are rows above the header row. Shopify may let you match headers manually in a Choose column headings window.
  • Illegal quoting on line and Missing or stray quote on line: often caused by curly quotes in a text cell.
  • Ignored line ... because it did not contain product data: check that the first row for each handle has a Title.
  • Ignored line ... because handle already exists: the handle is already in your store and overwrite is not ticked.
  • Validation failed: price can't be blank, Not a valid product category, Fulfillment service can't be blank and Inventory quantity is not a number: each points to one column.

Spreadsheet programs can also damage values before the file reaches Shopify. Leading zeros on barcodes and long SKUs are common casualties, so format those columns as text before you save.

Checking the file before you upload it

If you want a row-by-row check rather than finding errors one failed import at a time, Import Checker reads a Shopify product CSV in your browser and lists malformed fields and broken variant groupings, row by row, before you upload. A free preview shows the first findings, and the full report is a one-time purchase. It does not connect to your store, import anything or need an account.

For a plain-language reference to the format itself, see the Shopify CSV format guide.