Uploading Variants to Etsy
Created Feb 21, 2023
6 min read
Potential Errors
The most common error with variants occurs when you omit the variant options.
Opening the report, you will see the following error:
‘Invalid listing, has parent_sku
but no option1_name
. With parent_sku
, this listing has variants. Listings with variants must have option1_name
and option1_value
to explain what property changes between variants (ex: Color or Size)…’

WARNING: Underscore columns (ex: _primary_color
) have a special meaning.
Learn how to use them correctly: (see below “Etsy Built-in Options for Variants”).
How to quickly solve this error:
Do you want to have variants?
- No: Just empty the
parent_sku
column. - Yes: Follow the steps below to add variant options.
How to add variant options:
- Find the section in your template
option1_name
,option1_value
. - Add the name of the variant option, such as “Blanket Size” or ”
_primary_color
” **. - Add the values for each variant. “Small Blanket”, “Medium Blanket”
** Use the underscore column (_primary_color
) if you already added the values to that column in the template (_primary_color
in this example). These columns are special and are explained below in the section “Etsy Built-in Options for Variants”
Variant Options
Variant options explain which properties can change for each variant and how they change. For example, your variants options are Size and Color if your listing has different sizes and colors.
Without variant options, every product in a listing is the same - there’s no variation. That is why this causes errors when there are different variants, but no variation options.
Variant Options on Etsy
The variant options are controlled from the “Edit variations” menu on Etsy. Everything in this menu can also be uploaded with your Shop Uploader template.
In the example below:
option1_name
= Primary colouroption2_name
= Celebration

The option1_name is the same as the name of the first option in the variation menu. In our example that’s “Primary colour”

The option1_value
is the column “Primary colour” in the variant values table.
When your template is finished, the options section should look similar to the table on Etsy.
Etsy Built-in Options for Variants
Each product category has a limited number of properties that Etsy has made available as variant options. Different categories have different built-in properties.
The Etsy built-in properties are the underscore columns in your Shop Uploader template, such as _primary_color
.
When you generate a template and select your product categories, you are exporting a template that has columns for all the built-in properties that are allowed for the categories you selected.
You should use these Etsy Built-in properties for your variant options whenever possible. Etsy will include properties in your listing’s search index - it’s like having an extra tag for your each of your variant options. This will help you rank higher in search.

To create a listing with built-in options for variations. We can just enter the column name of the built-in property that changes for each variation.
In this example below, we create a listing with Etsy’s built-in options _primary_color
and _holiday
.
You may notice the option2_values (for _holiday
) are left blank. You may leave these blank if you already entered each value in the actual _holiday
column (earlier in the template). Shop Uploader will automatically copy the values from the _holiday
column into the option2_value
column.

Etsy Custom Options for Variants
Etsy allows custom properties to be used as variant options. When you type in your own option, instead of choosing from the list of available properties, you are creating a custom variation option.
Shops use custom options when their products have a variation not included in the Etsy built-in dropdown.

To create custom variation options in Shop Uploader, you just type in whatever option1_name
or option2_name
that you would like for your custom property. Shop Uploader will automatically take care of the rest.
In this example below, we create a listing with custom blanket options “Blanket Size” and “Stitching Color”.
