Template Documentation

The numeric ID for the listing. Generated by Etsy.

Leave the listing_id blank in your template to create new listings.

Provide a listing_id in your template to update an existing listing.

For existing listings, you can find listing_ids by clicking Start Export on the Exports page in the Download Listings section.

Must be a whole number

listing_id must match a listing in your Etsy shop

The numeric ID for each variant. Generated by Etsy.

Required to partial_update variants.

Exports with variants will include your product_ids. Exports are found on the Exports page.

Must be a whole number

product_id must match a listing variant in your Etsy shop (you have to export them)

The parent_sku groups multiple SKUs together into a single listing.

You can think of the parent_sku as the product SKU without the variant information. For instance our example: 'TOY-TRUK-50-RED' becomes 'TOY-TRUK' after removing the size (50) and the color (RED).

• Max 32 characters

• Cannot use spaces in your parent_sku

Your parent_sku should be formatted similar to the SKU.

Sometimes Shop Uploader will need to create dummy products for your Etsy listings and it will use the parent_sku to generate the dummy SKU.

Important Note: You should not use spaces in your parent_sku. If you need something like spaces use _ or - as separators instead.

The stock-keeping unit for your item.

The SKU must be unique for each product.

Important Note: You should not use spaces in your SKUs. If you need something like spaces use _ or - as separators instead.

Min 1 character

• Max 32 characters

• Cannot use ~ ` ! @ # $ % ^ & * = + \ | / ? . , > <

• Cannot end with ( [ {

Your SKU should provide useful information about the item to make it easily identifiable. If you don't have a SKU and don't want to create one, you can instead just provide random valid characters.

This is the title of your listing. A well crafted title will appear higher in search and entice shoppers to click on your listing.

There is only one title for a listing. Even if you provide a different title for each product variant, only the first title will be used.

Etsy's Title Requirements

• All listings require a title

• You must follow Etsy's Terms of Service.

• If you're syndicated for Google Shopping, you should also make sure your titles follow Google's Title Guidelines.

• Must start with a letter or number

• Max 140 characters

• Only one of each + : % &

• Cannot use $ ^ `

• Cannot have more than three words in all upper case

This tells the customers what they are buying in greater detail than the title. Here you can provide more details about the product, the services you offer, shipping, and return information.

Forum post with a list of usable special characters.

• You must follow Etsy's Terms of Service.

• You must follow Etsy's Seller Policy.

• Min 1 character

• Max 102,400 characters

• Only shows the first 160 in the search results

This is the price you want to sell your product for.

• Must be a number

• Min 0.20 USD equivalent (after conversion)

Max 50,000.00 USD

Make sure you account for Etsy fees when setting your price.

Etsy charges a $0.20 listing fee

5% transaction fee of the price you charge

5% shipping fee of the total cost your customers pay

Payment processing fee of 3% + $0.25 per transaction

2.5% currency conversion fee.

Learn more about Etsy fees.

How much of the item you have in your inventory. Enter the individual amounts for each variant.

Etsy shows the product's total quantity on its website. This is the sum of all your variant's quantities.

• Must be greater than or equal to 1

• Must be a whole number

• Etsy will only display quantities up to 999.

• You can enter any positive quantity in Shop Uploader, however, it will be capped at 999.

This column is availiable on custom made Shop Uploader templates

Category replaces the taxonomy_id column.

You add categories to your template through the Templates page. Once your desired categories are selected generate a new template.

You can either use your category's name or continue to enter the taxonomy ids.

Cannot be left empty.

Your options are limited to the categories you selected when generating the template.

These are additional properties you can add to your listing. The options availiable are based on the taxonomies/categories you chose when creating your template.

You must be using a custom generated Shop Uploader template.

If the property has a dropdown box, you must use one of the options provided.

Options are the product properties that change for your variants. If your variants change in color or size, these are your option names.

Product options can be custom properties or Etsy's built-in properties.

'Dress size' is a custom property because there is no preceeding underscore.

'_primary_color' is an Etsy built-in property because there is a preceeding underscore.

To use an Etsy built-in option, you use the column name like '_primary_color'.

You can only use '_property_columns' that exist in your template. The templates only contain the columns that are allowed for your product category. If your template is missing columns, you may need to generate a new template for your category.

• option1_name is required if option1_value is provided

• You can only use the Etsy built-in columns '_like_these' if they are in your template

• Min 1 character

• option1_name cannot change per variant.

• You must set at least option1_name and option1_value if your listing has variants

• Max 45 characters

• Cannot use ` $ ^

This is the value of the option1_name that changes for product variants.

For instance, when option1_name = 'Background color', option1_value is the 'Background color' of this variant.

If you use an Etsy built-in (option1_name = '_primary_color') and you have already entered the values in that column, you can leave the option1_value column empty and it Shop Uploader will copy the values over for you.

• Min 1 character

• Must have option1_name filled

• Max 255 characters

• Cannot use ` $ ^

Options are the product properties that change for your variants. If your variants change in color or size, these are your option names.

Product options can be custom properties or Etsy's built-in properties.

'Dress size' is a custom property because there is no preceeding underscore.

'_primary_color' is an Etsy built-in property because there is a preceeding underscore.

To use an Etsy built-in option, you use the column name like '_primary_color'.

You can only use '_property_columns' that exist in your template. The templates only contain the columns that are allowed for your product category. If your template is missing columns, you may need to generate a new template for your category.

• option2_name is required if option2_value is provided

• You can only use the Etsy built-in columns '_like_these' if they are in your template

• Min 1 character

• option1_name cannot change per variant.

• You must set at least option2_name and option2_value if your listing has variants

• Max 45 characters

• Cannot use ` $ ^

This is the value of the option2_name that changes for product variants.

For instance, when option2_name = '_material', this is the 'Material' value for this variant. If the variant is made of cotton you would enter cotton for the value, if suede enter suede.

• Min 1 character

• Must have option2_name filled

• Max 255 characters

• Cannot use ` $ ^

This is a variation control determines whether a variant should be enabled and purchaseable by customers.

By default all variations are enabled except dummy variations, which are disabled by default.

Value must be True or False

This is a variation control that means sku can change when option1_value changes.

For instance, when option1_value = 'RED', the SKU could be 'MY-SKU-RED' and then when option1_value = 'BLUE', the SKU could change to 'MY-SKU-BLU'.

This setting controls the checkboxes that you see on Etsy when creating variant options.

The main reason to use this option is when you want all your option1_values to have the same SKU.

Value must be True or False

This is a variation control that means price can change when option1_value changes.

For instance, when option1_value = 'RED', the price could be '12' and then when option1_value = 'BLUE', the price could change to '10'.

This setting controls the checkboxes that you see on Etsy when creating variant options.

The main reason to use this option is when you want all your option1_values to have the same price.

Value must be True or False

This is a variation control that means quantity can change when option1_value changes.

For instance, when option1_value = 'RED', the quantity could be '100' and then when option1_value = 'BLUE', the SKU could change to '26'.

This setting controls the checkboxes that you see on Etsy when creating variant options.

The main reason to use this option is when you want all your option1_values to have the same quantity.

If one sale uses up the inventory quantity of the whole listing (because options share assembly materials), you probably want this option to be FALSE.

Value must be True or False

This is a variation control that means sku can change when option2_value changes.

For instance, when option2_value = 'RED', the SKU could be 'MY-SKU-RED' and then when option2_value = 'BLUE', the SKU could change to 'MY-SKU-BLU'.

This setting controls the checkboxes that you see on Etsy when creating variant options.

The main reason to use this option is when you want all your option2_values to have the same SKU.

Value must be True or False

This is a variation control that means price can change when option2_value changes.

For instance, when option2_value = 'RED', the price could be '12' and then when option2_value = 'BLUE', the price could change to '10'.

This setting controls the checkboxes that you see on Etsy when creating variant options.

The main reason to use this option is when you want all your option2_values to have the same price.

Value must be True or False

This is a variation control that means quantity can change when option2_value changes.

For instance, when option2_value = 'RED', the quantity could be '100' and then when option2_value = 'BLUE', the SKU could change to '26'.

This setting controls the checkboxes that you see on Etsy when creating variant options.

The main reason to use this option is when you want all your option2_values to have the same quantity.

If one sale uses up the inventory quantity of the whole listing (because options share assembly materials), you probably want this option to be FALSE.

Value must be True or False

This is the url link to the image you want to post for your listing. This is the image you can link with image_for_option.

• Min 1 character

• Min size 50x50 pixels

• Recommended size 3000x3000 pixels

Only applies if you add images

You can either put all of your image's url links in this section or place the main one here and the rest into the images section.

Note images cannot be larger than 10MB.

Images are drawn from this category first for the Etsy slideshow based on image_position

For image requirements visit Requirements and Best Practices for Images in Your Etsy Shop.

For more information about images visit Etsy's Listing Image Requirements page.

Another useful source if information is Etsy's Intellectual Property Policy page.

This is the position you want your photo to show up in, in the Etsy slideshow. If you set the value to 1 it will show up first, if you set the value to 10 it will be last.

Must be a whole number

This section is optional. If you leave this blank your images will be listed in the order Shop Uploader finds them.

This is the item option the image will show up for. You need to enter the value you entered for either option1_name or option2_name into this column.

Cannot use ` $ ^

This section refers to columns: image_1 -> image_10.
Each column contains a URL to an image you want to upload to your listing. These numbered images are not linked to variants but they are uploaded in addition to the linked_image_url.

• Needs to be a URL

• Min size 50x50 pixels

• Recommended size 3000x3000 pixels

This section covers the image_1 to image_10 columns.

These images are processed and added to the Etsy slideshow after the ones from image_url have been added. Shop Uploader takes the images from image_1 from top to bottom first, then moves on to image_2 all the way to image_10.

For image requirements visit Requirements and Best Practices for Images in Your Etsy Shop.

For more information about images visit Etsy's Listing Image Requirements page.

Another useful source if information is Etsy's Intellectual Property Policy page.

This is the URL to the video you want to post for your listing. It follows the same URL requirements as images or digital files.

• Needs to be a url

• Over 5 seconds, under 1 minute

• Up to 100MB filesize

Videos will be cropped to a square and sound will be removed by Etsy

For video requirements view our Etsy video guide

The length of the product, when packaged, in the units specified in dimensions_unit.

The length applies to all product variants in the listing.

• Must be a number

• L >= W >= H

You must use the units that appear in the listing editor in your Etsy shop

We recommend using the smallest unit allowed by your Etsy shop and using it across your entire product catalog.

If your product length does not show up on Etsy it probably means Etsy does not like your selected dimensions_unit.

The width of the product, when packaged, in the units specified in dimensions_unit.

The width applies to all product variants in the listing.

• Must be a number

• L >= W >= H

You must use the units that appear in the listing editor in your Etsy shop

We recommend using the smallest unit allowed by your Etsy shop and using it across your entire product catalog.

If your product width does not show up on Etsy it probably means Etsy does not like your selected dimensions_unit.

The height of the product, when packaged, in the units specified in dimensions_unit.

The height applies to all product variants in the listing.

• Must be a number

• L >= W >= H

You must use the units that appear in the listing editor in your Etsy shop.

We recommend using the smallest unit allowed by your Etsy shop and using it across your entire product catalog.

If your product height does not show up on Etsy it probably means Etsy does not like your selected dimensions_unit.

Defines the unit for the length, width, and height. Each measurement must use the same unit.

You may need to do some testing with the different options to determine which works for your shop.

The weight of the item and packaging (applies to the entire listing).

Must be a number

Certain accounts cannot ship domestic packages over 70 pounds.

You must use the units that appear in the listing editor in your Etsy shop

We recommend using the smallest unit allowed by your Etsy shop and using it across your entire product catalog.

Enter 2000 oz if the item weights 125 lbs or 2000 g if the item weights 2 kg.

If your product weight does not show up on Etsy it probably means Etsy does not like your selected weight_unit.

Defines the unit for the weight.

You may need to do some testing with the different options to determine which works for your shop.

The numeric ID of the shipping profile associated with the listing.

You can find this on your Shop page.

shipping_profile_id must match a shipping profile in your Etsy shop

The numeric ID of the return policy associated with the listing.

Return policies are mandatory for most Etsy listings as of Jan 31, 2023 (does not apply to EU-based shops).

You can find this on your Shop page.

return_policy_id must match a return policy in your Etsy shop

This section refers to columns: digital_file_1 -> digital_file_5

This is the url link(s) to the digital file(s) you want to post for your listing.

Etsy allows 5 digital files per listing, if you need more than this, you can use ZIP folders.

• type must be set to digital

• Must be a url

• File size cannot be greater than 20MB

• File name must be between 3 and 70 characters long

This section refers to columns: digital_file_name_1 -> digital_file_name_5

This is where you add your digital file's name.

This is needed since some urls do not provide this information. Without this information, your customer have to add the file extension themselves after purchaing your products.

• type must be set to digital

• digital_file must have an entry

• File name must be between 3 and 70 characters long

This indicates if the product is a physical or digital product.

You will need to indicate what type of items you are selling. This is a mandatory field when listing a product on Etsy.

The numeric ID of the shop section for this listing.

You can find this on your Shop page.

A unique Etsy defined code that helps categorize listings on Etsy

You can find these on the Templates page.

If you are using a Shop Uploader custom template, taxonomy_id is covered by the category column.

Must be greater than or equal to 1

Who made the product.

Is the product made to order?

If TRUE it is made to order. If FALSE it is not made to order.

Must be True or False

Is the product considered vintage (20+ years old).

If TRUE the produce is >=20 years old. If FALSE the product is <20 years old.

• Item must be at least 20 years old

• Item age is based on year_made value

This is the year in which the product was produced.

• Must be a whole number

• year_made <= Current Year

• If from BC/BCE, use negative numbers

NOTE: All listing fees are levied by Etsy. Shop Uploader has no control over fees levied by Etsy.

This indicates whether or not you want your listings to be automatically renewed.

When TRUE, renews a listing for four months upon expiration.

If TRUE when previously FALSE, Etsy renews the listing before it expires, but the renewal period starts immediately rather than extending the listing's expiration date.

Any unused time remaining on the listing is lost. Renewals result in charges to a user's bill.

Value must be TRUE or FALSE

This indicates whether or not a customer will be taxed at checkout when purchasing the item.

When TRUE, applicable shop tax rates apply to this listing at checkout.

Value must be TRUE or FALSE

When TRUE, tags the listing as a supply product. False indicates that it is a finished product. Helps buyers locate the listing under the Supplies heading.

• who_made is set

• year_made is set

TRUE indicates that the item is a supply or tool used to make things.

False indicates that the item is a finished product.

When TRUE, a buyer may contact the seller for a customized order.

When TRUE, this listing is personalizable.

Value must be TRUE or FALSE

When TRUE, this listing requires personalization.

• Value must be TRUE or FALSE

• When TRUE, is_personalizable must also be TRUE

Instructions telling the buyer on what to put in the personalization text box.

When TRUE, is_personalizable must also be TRUE

• Cannot use ` $ ^

• Max characters 256

The maximum length for the personalization message entered by the buyer.

• is_personalizable must also be TRUE

• Minimum character amount is 1

• Value must be a whole number

• Max 1024 characters

• Cannot have ,

This defines the style of the product you are selling.

• Cannot be more that 45 characters long

• Max 2 per listing

• Cannot use ~ ` ! @ # $ % ^ & * ( ) _ + = [ ] { } \ | / ? > < . ,

• Cannot contain emoji

This section refers to columns: tag_1 -> tag_13

A tag is a word or short phrase that describes your item.

• Max 20 characters

• Max 13 per listing

• Cannot use ~ ` ! @ # $ % ^ & * ( ) _ + = [ ] { } \ | / ? > < . ,

This section refers to columns: material_1 -> material_13

Materials are what your products are made out of.

• Emojis 👎

• Cannot use ~ ` ! @ # $ % ^ & * ( ) _ - + = { } [ ] | \ / , . < >

• Max 13 per listing

• Max 45 characters

This section refers to columns: production_partner_1 -> production_partner_5

These are the IDs of your Etsy production partners. Etsy automatically generates the IDs but you have to create the production partners.

You can create your production partners by going to Shop Manager > Settings > Production Partners on Etsy.

You can access these on your Shop page (must be logged in).

For additional information please visit the Working With Production Partners on Etsy page.

Action controls how Shop Uploader will process your upload. This is the most important column in your template.

create/update creates a new listing or updates an existing listing (overwrites everything). If you provide a listing_id, it will overwrite all information in your listing. Without a listing_id, the update action will create a new listing. Both create and update perform the same actions, different names, same result.

inventory will ONLY change inventory quantity (but it's very fast). You must provide listing_id, sku, and quantity.

delete will deletes the listing. You need to also provide listing_id.

state_change ONLY change the listing_state, for instance changing a draft listing into an active listing. You must provide listing_id.

partial_update will ONLY update the columns you provide. You must provide listing_id (and product_id to update variants).

This describes the listing state of your listings. The two options for this category are draft and published.

When set to draft you will upload draft listings. A draft listing is free to make and is not seen by customers.

When set to publish you will upload published listings or change your draft listings into published listings. Published listings are public and can be seen by customers. You have to pay Etsy's listing fee ($0.20) to post a published listing.

You cannot take a listing from active to draft.

If TRUE and you already have 10 images existing images will be overwritten.

If overwrite is FALSE, the new images will be added after the existing images. This is until you hit the max image limit for the listing. Once hit additional images will be ignored.

Value must be True or False

If TRUE, Shop Uploader will deactivate a listing when the listing and all its variants have 0 quantity.

This solves the 'EtsyError: listing quantity cannot be 0' when trying to set the inventory to 0 (sold out) for a listing.

Listings cannot be changed to the state 'sold_out' via the API. So, we must instead change listings to 'inactive'.

Re-activating a listing may incur Etsy listing fees, so this is FALSE by default.

Value must be True or False

If TRUE, delete all images from the listing before adding any images.

This is useful when you are uploading new images, but fewer than are currently online, and you don't want any of the old images.

Value must be True or False

If TRUE, delete all variants from the listing before adding any variants.

This can be used with the `partial_update` action to simply remove all variants.

Value must be True or False