Upload listings to Etsy

Learn how to upload listings to Etsy with Shop Uploader.

Getting started

This guide will serve as a starting point to introduce the Shop Uploader template and the sections that you need to complete to bulk upload listings to Etsy.


Check out the Template documentation for more details on every column.

All templates share the same structure but you can customize your template to include category-specific properties and translations.

Template sections (in order):

  1. Identifiers
  2. Title and description
  3. Price and inventory
  4. Category properties
  5. Variation options
  6. Images
  7. Videos
  8. Shipping
  9. Policies
  10. Digital files
  11. Listing details
  12. Production partners
  13. Translations
  14. Controls


The listing identifiers are: listing_id, parent_sku, sku.

  • When updating an existing listing, you provide the listing_id which is exported from Etsy.
  • When creating a listing with variations, the parent_sku determines which variations will be part of the listing.

Here is an example that would create a new listing with 3 variations:

listing_id parent_sku sku

Category attributes and _underscore_columns

The category column and the category attributes are the most important attributes for search optimizing your listings.

They “are like free ‘super tags’” according to Etsy’s search handbook.

Adding category properties with Shop Uploader:

  1. Generate a template with categories
  2. Choose the category in your template
  3. Enter property values in the _underscore_columns


category is the most important listing attribute. This will determine the area your product is sold on Etsy.

On Etsy, the product category is chosen with the category search.

Category selector on Etsy.

In the Shop Uploader template, category is chosen with a dropdown. You add categories to the dropdown when you generate a template.

Category selector in Shop Uploader template.

Properties (_underscore_columns)

On, Etsy the properties are all the various attributes in the middle of the listing form.

Category selector in Shop Uploader template.

Property columns are all the _underscore_columns in the template.

Category selector in Shop Uploader template.
  • _underscore_columns are special
  • _underscore_columns change for each category
  • _underscore_columns change in different templates

The underscore columns like _primary_color, _holiday, etc. are category-specific properties. This section of the template will change depending on which categories you selected when generating your template.

Only certain values are allowed for each category, so the allowed values for _underscore_columns may change when using different categories.

Some properties will require scales. For instance dimension properties such as _width will require a scale. Add scales with a space like this:

_primary_color _width _height
Red 4 in 2 in


Shop Uploader lets you bulk upload images to Etsy with URLs.


  • Etsy allows up to 10 images on a listing.
  • Images must be accessible via public URL
  • Image URLs must be directly to the file, not a preview
  • Shop Uploader will only upload 10 images, if you provide more than 10


  • Integrations are available for Google Drive and Dropbox.
  • These integrations will allow you to keep your URLs private.
  • You can also use file paths instead of URLs.

There are two types of images:

  • Images linked to variations
  • Regular images

Images linked to variations

Images can be linked to a variation option, such as Color. When a customer selects the variation option ‘Red’ the image on Etsy will change to your red image.

Link images to variations with: linked_image_url, linked_image_position, linked_image_for_option.

  • linked_image_url is the URL for the image.
  • linked_image_position (optional) is the position, 1-10, of the image.
  • linked_image_for_option is the option_name to link the image to (ex: Color).
  • linked_image_alt_text is the alt_text for the image.


This example would link the images to the Primary color, so that when the customer selects a different color, the image will change to that color.

option1_name option1_value linked_image_url linked_image_position linked_image_for_option
Primary color Red https://url.com/img/red.png 2 Primary color
Primary color Blue https://url.com/img/blu.png 3 Primary color
Primary color Green https://url.com/img/grn.png 4 Primary color

Regular images

To simplify the upload process, you can add all your URLs to your template. Add them in order of priority, so all URLs in image_1 are more important than image_2.

If you have more than 10 images, Shop Uploader will follow this order of priority to assemble a list of 10 image urls.

This is how images are assembled in Shop Uploader:

Image upload priority.
  1. Images linked to variations
  2. image_1
  3. image_2
  4. image_10

Any duplicate URLs are ignored, but if your template has differing images in the same column the results will be as follows:

Will result in 3 images on the listing.

Notice both image_1 URLs are positioned before the image_2 URLs.

Physical listings

Physical listings are regular products that are shipped to customers.


  • Must select type physical
  • Must provide shipping_profile_id
  • Must provide return_policy_id
  • Cannot have any digital files


Products can have fixed shipping or calculated shipping. This is decided within the shipping profile that you setup on Etsy.

Fixed shipping

Fixed shipping products only require the shipping_profile_id.

Calculated shipping

Calculated shipping requires the package dimensions: length, width, height, dimensions_unit, weight, weight_unit.

These dimensions are for the product, in a box, ready to ship.

These dimensions define the calucated shipping settings for the entire listing. The calculated shipping dimensions cannot change per variation.

Digital listings

Digital listings will allow shoppers to download digital files upon purchase.


  • Must select type digital
  • Must provide at least one digital_file
  • Shipping sections left blank

Digital files

digital_file is the URL to your digital file.
digital_file_name is the file name with the file extension.

Make it easier for your customers to understand your files with good file names. You must include the extension (like .pdf, .jpg) or your file will be harder to open.

Each column is numbered: digital_file_name_1 is the file name for digital_file_1

digital_file_1 digital_file_name_1 digital_file_2
https://exampleurl.com/file/1.pdf your_product.pdf


Shop Uploader controls are available to choose how your upload functions. In future versions of Shop Uploader more of these options will be available directly on the uploads page.

The most powerful
tool for Etsy sellers