Variant Options Import: How to Format Product Variants Right
A variant options import adds products that come in several versions, such as a shirt in different sizes and colors, from a single spreadsheet. Every ecommerce platform handles this with the same basic idea: one parent product holds the shared details, and each variant gets its own row with its option values, SKU, price and stock.
The difference is in the details. Shopify, WooCommerce and Wix each use different columns to link variants to their parent and to list option values. Get those columns wrong and you end up with dozens of separate products instead of one product with variants.
How Variant Options Work in an Import File
Variant options have two parts: the option name, which is the attribute that varies, such as Size or Color, and the option values, which are the choices within it, such as Small, Medium and Large. Each variant is one combination of values, like Medium and Navy, with its own SKU, price and inventory.
In an import file, that structure becomes a parent row plus one row per variant. The parent carries information that’s the same for every version, such as the title, description and brand. Each variant row carries only what differs, along with an identifier that links it back to its parent.
Before formatting anything, it helps to map out the full set of combinations. Here’s an example for a T-shirt sold in two sizes and two colors, which produces four variants:
| Variant | Size | Color | SKU | Price |
|---|---|---|---|---|
| 1 | Small | Navy | TEE-S-NVY | 24.00 |
| 2 | Small | Gray | TEE-S-GRY | 24.00 |
| 3 | Medium | Navy | TEE-M-NVY | 24.00 |
| 4 | Medium | Gray | TEE-M-GRY | 24.00 |
Two rules apply on every platform. Each combination of option values should appear only once, and each variant needs its own unique SKU. Duplicate combinations or SKUs are among the most common reasons a variant import fails or produces confusing results.
How to Format Variant Options for Shopify, WooCommerce and Wix
Each platform translates the parent-and-variant model into its own columns. The table below summarizes the key differences, and the sections that follow show how the T-shirt example looks on each one.
| Platform | How variants link to the parent | Where option values go |
|---|---|---|
| Shopify | Same URL handle on every row | Option1, Option2 and Option3 name and value columns (up to 3 options) |
| WooCommerce | Parent column holding the parent’s SKU or ID | Numbered attribute name and value(s) columns |
| Wix | Same handleId on product and variant rows | productOptionName, productOptionType and productOptionDescription columns (up to 6 options) |
Shopify
In Shopify’s product CSV, all rows for one product share the same URL handle. The first row holds the full product details, while later rows for the same handle leave Title, Description, Vendor and Tags blank and fill in only variant data. A product can have up to three options, using the Option1, Option2 and Option3 name and value columns.
| URL handle | Title | Option1 name | Option1 value | Option2 name | Option2 value | SKU | Price |
|---|---|---|---|---|---|---|---|
| trail-tee | Trail Tee | Size | Small | Color | Navy | TEE-S-NVY | 24.00 |
| trail-tee | Small | Gray | TEE-S-GRY | 24.00 | |||
| trail-tee | Medium | Navy | TEE-M-NVY | 24.00 | |||
| trail-tee | Medium | Gray | TEE-M-GRY | 24.00 |
Variant columns such as SKU, price and weight depend on the option columns, so every variant row needs its option values filled in. When you update existing products with Overwrite products with matching handles selected, keep the option columns in the file. Leaving them out can delete existing variants and replace them with a single default variant.
WooCommerce
WooCommerce’s product CSV importer uses a Type column to separate the parent from its variations. The parent row uses variable, and each variation row uses variation. Variation rows point to their parent through the Parent column, which takes the parent’s SKU or its numeric ID with an id: prefix, such as id:100.
| Type | SKU | Parent | Name | Attribute 1 name | Attribute 1 value(s) | Attribute 2 name | Attribute 2 value(s) | Regular price |
|---|---|---|---|---|---|---|---|---|
| variable | TEE | Trail Tee | Size | Small, Medium | Color | Navy, Gray | ||
| variation | TEE-S-NVY | TEE | Size | Small | Color | Navy | 24.00 | |
| variation | TEE-S-GRY | TEE | Size | Small | Color | Gray | 24.00 | |
| variation | TEE-M-NVY | TEE | Size | Medium | Color | Navy | 24.00 | |
| variation | TEE-M-GRY | TEE | Size | Medium | Color | Gray | 24.00 |
Notice the difference between rows. The parent lists every possible value for an attribute, separated by commas, while each variation needs only one value per attribute. If a variation row contains several values, WooCommerce uses the first one.
The parent row can also use Attribute 1 default to set the variation shown first, and the visible and global attribute columns take 1 or 0. If the attribute name matches a global attribute in your store, WooCommerce uses it. Otherwise, it creates the attribute as plain text for that product.
Wix
Wix Stores uses a fieldType column to mark each row as Product or Variant. Variant rows must use the same handleId as their product, and they leave the name and price blank. If a variant costs more or less than the base price, its surcharge column holds the difference, which can be positive or negative.
Options are defined with three sets of columns. productOptionName holds the option, such as Size, productOptionType must be DROP_DOWN or COLOR in capitals, and productOptionDescription holds the choices.
On the product row, list all choices separated by semicolons. On each variant row, enter that variant’s choice.
Color options need a hex or RGB value plus a label, such as #000080:Navy;#808080:Gray, while drop-down choices are plain text of up to 20 characters. Wix allows up to six options per product, SKUs up to 40 characters and up to 5,000 rows per file. Because Wix doesn’t allow you to add, delete or rename template columns, start from its CSV template, which includes sample products with variants you can copy.
Common Variant Import Errors and How to Fix Them
Most variant problems come from a broken link between rows or from option values that don’t line up. The table below covers the issues that appear most often across platforms.
| Problem | Likely cause | Fix |
|---|---|---|
| Each variant imports as a separate product | The linking value differs between rows, such as a typo in the handle, Parent SKU or handleId | Make the linking value identical on the parent and every variant row. |
| WooCommerce variations don’t attach to the parent | The Parent column doesn’t match the parent’s SKU, or the parent row is missing | Include the parent row and check that its SKU matches exactly. |
| Variants disappear after an update | Shopify option columns were left out of an overwrite file | Re-import the variant rows with the option columns included. |
| Import rejects duplicate variants or SKUs | Two rows share the same option combination or SKU | Give each combination one row and each variant a unique SKU. |
| Too many options for one product | More options than the platform allows, such as four in Shopify | Combine or drop the least important option before importing. |
| Extra values such as both “S” and “Small” | Inconsistent spelling or abbreviations across rows | Standardize values before importing. |
| Wix reports an error on a product row | Wix reports variant and media errors against the product row | Check the variant rows directly below the reported row. |
| Shopify shows “Line is invalid (No details)” | An existing option value moved to a different option position | Import once with a temporary option name, then again with the final name. |
Changing option values on products that already exist deserves extra caution. In Shopify, editing a value such as “Small” to “S” creates new variant IDs rather than renaming the old ones, which can break apps and integrations linked to those variants. Other platforms can behave similarly, so rename options deliberately and test on a single product first.
Whatever the platform, test with one or two products before importing the full file. Choose a product with every option your file uses, then confirm each variant has the right values, SKU and price.
Keep Option Names and Values Consistent
Consistent option data prevents many import errors before they happen. Decide on one spelling for each option name, such as Color rather than a mix of Color and Colour, and one format for each value, such as Small, Medium and Large rather than S, M and L on some products. Inconsistent values don’t just look untidy, because the platform treats each spelling as a different choice.
A short reference list helps when several people or suppliers contribute product data. Record the approved option names, their values and the order they should appear in, and check incoming spreadsheets against it before importing. This matters even more when you sell on more than one platform, since each import file needs the same values in a different layout.
If you manage variant data across stores, Bulkflow can reduce the reformatting. It supports Shopify, WooCommerce and Wix, with bulk import and field mapping, so you can match your spreadsheet columns to each platform’s fields instead of rebuilding every file by hand.
Conclusion
A successful variant options import comes down to one consistent structure, a parent with linked variant rows, written in the columns your platform expects. Once you’ve mapped your option combinations and matched each platform’s format, importing products with variants becomes a repeatable task rather than a source of duplicate listings. We hope this guide helps you import variant options cleanly into your store. If you manage product data across platforms regularly, you can explore Bulkflow.
