Importing Product Variant Fields from Google Sheets

This tutorial assumes you already know how One-Way Import works and how to configure it. If not, please review the How to Import Data from Google Sheets into Shopify tutorial first.

One-Way Import reads a spreadsheet you already have and writes it into Shopify, so your columns can be named anything - in the Format Data step you map each of your columns to the Shopify field it means. This guide is a reference for the variant-level fields you can map to, and the format each one expects in the cell.

Variant-level fields are the ones that differ between variants of the same product: option values, SKU, barcode, price, weight, and so on. For fields that describe the product as a whole, see Importing Product Fields from Google Sheets. For images, see Importing Product Images from Google Sheets.

1. One row per variant

In One-Way Import, a row is a variant. A product with three variants is three rows that share a product identifier - normally the same Handle (Product) repeated on each row.

Rows are grouped into products by Handle (Product), then Title (Product), then Id (Product). Product-level fields are written once, from the first row of the group; variant-level fields are written from every row. So a typical multi-variant layout looks like this:

The handle repeats on every row. The title and option name are only needed on the first row - eCommix carries option names down to the remaining rows in the group automatically. The option value, SKU, and price are filled on every row, because each one describes a different variant.

2. How a row is matched to a variant

eCommix resolves the variant a row refers to using your mapped identifier columns, in this order:

• Id (Variant) - An exact match. Accepts a bare numeric ID (44123456789012) or a full global ID (gid://shopify/ProductVariant/44123456789012).
• SKU (Variant) - Looks up the variant by SKU across the store. Also resolves the parent product, so a SKU-only sheet works without a handle.
• Barcode (Variant) - Used when there is no SKU on the row; same behaviour as SKU.

If one of these resolves an existing variant, the row updates it. If none of them do but the row identifies a product, the row creates a new variant on that product. A row with no product and no variant identifier at all is skipped.

Info. SKU and Barcode lookups search your whole store, so make sure they are genuinely unique before relying on them. If a SKU exists on two variants, the row updates whichever Shopify returns. When your sheet already has variant IDs - for instance from an eCommix export - map Id (Variant) instead; it is exact and needs no lookup.

3. Option values

Option values pair with the option names, which are product-level columns - Option 1 Name (Product) and so on. Creating a variant requires Option 1 Name (Product) and Option 1 Value (Variant) together; without both, the row fails with a message naming the two columns to map.

For a product with a single variant and no real options, use Shopify's convention: option name Title, option value Default Title.

Warning. Within one product group, each variant row must use a unique combination of option values. Two rows under merino-wool-beanie that both say Charcoal are reported as a duplicate and are not imported - Shopify cannot hold two variants with the same options. If you have a legitimately different variant, give it a different option value or add a second option.

4. Identifiers and pricing

Warning. Price columns must contain a plain number. A cell holding $39.00, 39,00, or USD 39 is not a valid number and the row will fail. If your source data is formatted as currency text, strip the symbol and use a period for decimals before importing - in Google Sheets, formatting a column as Number rather than Currency is usually enough.

Cost Per Item (Variant) is stored on the inventory item rather than the variant itself, so it is written in a follow-up call after the variant is saved. If it fails, you will see it as a warning on an otherwise successful row.

5. Inventory and shipping behaviour

Boolean columns accept TRUE, YES, or 1 in any case as true; every other non-blank value is read as false. A blank cell is skipped entirely rather than treated as false, so write FALSE explicitly when you mean false.

Info. Stock quantities are not a variant field. Mapping a column to Inventory Quantity (Variant) or Quantity (Line Item) produces a warning and changes nothing, because Shopify holds quantities per location. To import stock levels, map your quantity column to Inventory Available (<Location> Location) instead, choosing the location from the field picker.

6. Weight and unit price

Warning. Weight Value (Variant) and Weight Unit (Variant) must always be supplied together. A weight value with no unit is ignored, and a unit with no value does nothing - so if weights are not appearing in Shopify, check that both columns are mapped and both cells are filled on that row.

Unit price fields are only relevant for stores that display unit pricing - common for EU markets selling by volume or weight. The base measure value is rounded to a whole number.

7. Customs and origin

Country and province codes are upper-cased for you, so nz and NZ both work. They must be the codes, though - New Zealand is not accepted.

8. Variant images and metafields

Map Image Src (Variant) to set the variant's featured image from a public URL. Unlike product images, this is applied per row, so each variant row can carry its own image. See Importing Product Images from Google Sheets for the details.

Variant metafields, inventory levels per location, and region catalog prices also appear in the field picker and are applied per variant row, after the variant itself is saved.

9. Validate before importing

Run Validate first - it checks every row against Shopify without writing anything - then read the STATUS column in your sheet. For variant work the statuses to look for are:

• VARIANT CREATED - a new variant was added to an existing product.
• VARIANT UPDATED - an existing variant was matched and updated.
• PRODUCT UPDATED/VARIANT CREATED - the product was updated and a new variant added from the same row.
• PRODUCT/VARIANT CREATED - a brand new product and its first variant, both from that row.
• ... WITH WARNINGS: ... - the row was written, but something needs attention; the warning text follows the colon.

FAQ

How do I add a new variant to a product that already exists?

Add a row that identifies the product - normally its Handle (Product) or Id (Product) - and leave the variant identifiers empty. Fill in Option 1 Name (Product) and Option 1 Value (Variant) with an option value the product does not already have, and eCommix creates the variant rather than updating an existing one.

Why did my row fail with a duplicate option value error?

Two rows in the same product group carry the same combination of option values. Shopify cannot store two variants with identical options, so eCommix reports the duplicate instead of overwriting one with the other. Give each variant row a distinct option value combination.

Can I import variants using only SKUs, with no handle column?

Yes. A SKU resolves both the variant and its parent product, so a sheet of SKUs and prices is enough to bulk-update existing variants. You do need a product identifier when creating variants, since a new variant has no SKU in Shopify yet to look up.

Why is my price not importing?

Almost always because the cell is not a plain number. Currency symbols, thousands separators, and comma decimal separators all make the value unparseable. Format the column as Number in Google Sheets and use a period for decimals - 39.00, not $39,00.

Why did the weight not change in Shopify?

Weight needs both Weight Value (Variant) and Weight Unit (Variant) on the same row. If either is missing or blank, the weight is skipped silently rather than half-applied.

How do I import stock quantities alongside my variants?

Map your quantity column to Inventory Available (<Location> Location), picking the location from the field picker. Quantities live per location in Shopify, so the generic Inventory Quantity (Variant) field cannot set them and will warn you if mapped.