Import Builder
Import Builder/Guides/Product variants in a CSV
E-commerce

Product Variants in a CSV: How Shopify, WooCommerce and Squarespace Lay Them Out

A spreadsheet has one row per line, but a T-shirt in three sizes is one product with three variants. Every platform solves that differently, and most product import problems come from mixing up the layouts.

How variants work in a CSV

A variant is one combination of options: Size M, or Size M in Blue. Each variant usually needs its own row, because it has its own SKU, price and stock. What differs between platforms is how those rows are tied back to their product: Shopify groups them by URL handle, WooCommerce links each variation to a parent row by SKU, and Squarespace repeats the product on every row. The same three-size T-shirt is shown in each format below.

Shopify

One row per variant, grouped by URL handle. Product details such as title, description, vendor and tags go on the first row only; the rows after it give the handle and that variant's own details.

URL handle,Title,Option1 name,Option1 value,SKU,Price,Product image URL,Image position
logo-tee,Logo T-shirt,Size,S,TEE-01-S,25.00,https://example.com/tee-front.jpg,1
logo-tee,,,M,TEE-01-M,25.00,https://example.com/tee-back.jpg,2
logo-tee,,,L,TEE-01-L,27.00,,
  • Up to 3 options per product (Option1 to Option3).
  • Images take one row each, in Image position order, up to 250 per product. A variant's own picture goes in Variant image URL.
  • Handles use letters, numbers and dashes, with no spaces.
  • Changing option values on existing products replaces their variant IDs, which can break apps that rely on them.

WooCommerce

A parent row with Type variable lists every value of each attribute. Each variation is its own row, with Type variation, its own SKU and name, one value per attribute, and the parent's SKU in Parent.

Type,SKU,Name,Parent,Attribute 1 name,Attribute 1 value(s),Regular price
variable,TEE-01,Logo T-shirt,,Size,"S, M, L",
variation,TEE-01-S,Logo T-shirt - S,TEE-01,Size,S,25
variation,TEE-01-M,Logo T-shirt - M,TEE-01,Size,M,25
variation,TEE-01-L,Logo T-shirt - L,TEE-01,Size,L,27
  • Parent can be the parent's SKU or id:123.
  • Leave ID blank for new products and variations.
  • Attribute 1 global is 1 for an attribute set up in the store, 0 for one that only exists on this product.
  • From WooCommerce 11.1 the parent row must come before its variations to convert a product in one import.

Squarespace

One row for every combination of options, using Option Name and Option Value columns numbered 1 to 3. The description goes on the product's first row only.

Title,Option Name 1,Option Value 1,SKU,Price
Logo T-shirt,Size,S,TEE-01-S,25
Logo T-shirt,Size,M,TEE-01-M,25
Logo T-shirt,Size,L,TEE-01-L,27
  • Up to 250 variants per product.
  • Variant images can't be set in the file: add them after the import.
  • This shows the variant columns only. Start from the template Squarespace gives you under Products, Import, which has the exact headers.

Common mistakes

Product details repeated on every row

Platforms that group rows by product expect the product's details once. Repeating a slightly different title or description on a variant row can overwrite the product, or start a new one.

Two rows with the same options

Each variant is one unique combination, such as Size M and Colour Blue. Two rows with the same combination is a duplicate the platform can't tell apart.

The same value spelled two ways

M and Medium, or Navy and navy, become separate options. Pick one spelling and use it on every row.

Rows that lose their product

A typo in a Shopify handle or a WooCommerce Parent SKU leaves variants without their product. Copy identifiers rather than retyping them.

Too many options or variants

Shopify and Squarespace allow up to 3 options per product, and Squarespace up to 250 variants. Split very large ranges into separate products.

Missing SKUs

Without a unique SKU per variant, stock, orders and later updates are hard to match up. Give every variant its own.

Platform-specific fixes are in Shopify product CSV import errors and WooCommerce product CSV import errors.

Collecting variants from suppliers?

The multi-channel product variant template collects one row per variant with its SKU, variant, price and quantity, checked as it's entered. For a specific platform, use the Shopify or WooCommerce products template.

Try the variant template

Related Guides

Relevant Templates

Import Builder is an independent product and is not affiliated with, endorsed by, or sponsored by Shopify, Automattic (WooCommerce) or Squarespace. Their names are trademarks of their respective owners. Layouts as described in each platform's help documentation, October 2026.