Uploading Variations to Etsy

Created Feb 21, 2023

6 min read

Potential Errors

The most common error with variations occurs when you omit the variation 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 variations. Listings with variations must have option1_name and option1_value to explain what property changes between variations (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 Variations”).

How to quickly solve this error:

Do you want to have variations?

  • No: Just empty the parent_sku column.
  • Yes: Follow the steps below to add variation options.

How to add variation options:

  1. Find the section in your template option1_name, option1_value.
  2. Add the name of the variation option, such as “Blanket Size” or ”_primary_color**.
  3. Add the values for each variation. “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 Variations”

Variation Options

Variation options explain which properties can change for each variation and how they change. For example, your variations options are Size and Color if your listing has different sizes and colors.

Without variation options, every product in a listing is the same - there’s no variation. That is why this causes errors when there are different variations, but no variation options.

Variation Options on Etsy

The variation 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 colour
  • option2_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 variation values table. When your template is finished, the options section should look similar to the table on Etsy.

Etsy Built-in Options for Variations

Each product category has a limited number of properties that Etsy has made available as variation 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 variation 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 variation 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 Variations

Etsy allows custom properties to be used as variation 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”.

The most powerful
tool for Etsy sellers