Template Documentation

The numeric ID for an Etsy 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 an Etsy product variation. Generated by Etsy.

Required to partial_update variations.

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

Etsy may change the product_id whenever you make changes to a listing's variations.

Must be a whole number

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

The parent_sku is a string that combines rows together to create variations.

Any rows with the same parent_sku will be variations inside one listing.

The parent_sku is not actually uploaded to Etsy, it is just used to describe which rows in the template belong together.

Related documentation: Variations

• 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 variation, 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 variation.

Etsy shows the product's total quantity on its website. This is the sum of all your variation'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.

Category defines what kind of product you're selling and where it should appear in Etsy searches.

Category is the most important product data and significantly impacts SEO.

You can add categories to your templates when creating them.

Cannot be left empty.

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

These are additional properties/attributes you can add to your listing. The options available 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 variations. If your variations 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.

Related documentation: Variations

• 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 variation.

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

• Max 45 characters

• Cannot use ` $ ^

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

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

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.

Related documentation: Variations

• Min 1 character

• Must have option1_name filled

• Max 255 characters

• Cannot use ` $ ^

Options are the product properties that change for your variations. If your variations 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.

Related documentation: Variations

• 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 variation.

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

• Max 45 characters

• Cannot use ` $ ^

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

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

Related documentation: Variations

• Min 1 character

• Must have option2_name filled

• Max 255 characters

• Cannot use ` $ ^

This is a variation control determines whether a variation 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 variation 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 variation 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 variation 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 variation 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 variation 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 variation 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 for the image you want to link to a variation.

A linked image is linked to a variation option (ex: Color) and when the customer selects that option, Etsy will display the linked image.

The image is linked by using this column and image_for_option

Many option values can be linked to the same image, for example all Sizes linked to a size chart.

Only one image can be linked to each option value. Example: Customer selects Red, only one image will appear.

Learn more about linking images to variations.

• 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 of the linked image in the Etsy image set.

Positions will be automatically corrected, and can be used to set relative position:

If you want the image to be first, use 1.

If you want the image to be last, use 10.

Learn more about linking images to variations.

Must be a whole number

This column is optional. Shop Uploader will use ascending order (1,2,3) by default.

This is the variation option name for the linked image.

For instance, to link the image to this variation's Size, the linked_image_for_option would be Size.

Enter the value from option1_name or option2_name into this column.

Learn more about linking images to variations.

Cannot use ` $ ^

Alt text for the linked image. Providing alt text can improve the SEO of your listings.

Learn more about linking images to variations.

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 cannot be linked to variations. They are uploaded in addition to the linked_image_url.

Learn more about images.

• Must 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 linked_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 section refers to columns: image_alt_text_1 -> image_alt_text_10.
Each column contains the alt text for the corresponding numbered image column (example: image_1 & image_alt_text_1). Providing alt text can improve the SEO of your listings.

Learn more about images.

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.

• Must 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 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

Calculated shipping only.

The length of the package, ready to ship. Units are specified in dimensions_unit. The length applies to all product variations 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.

Calculated shipping only.

The width of the package, ready to ship. Units are specified in dimensions_unit. The width applies to all product variations 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.

Calculated shipping only.

The height of the package, ready to ship. Units are specified in dimensions_unit. The height applies to all product variations 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.

Calculated shipping only.

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

You may need test different units. Different units are supported depending on your shop's location.

Calculated shipping only.

The weight of the package, ready to ship. Units are specified in weight_unit. The weight applies to all product variations in the 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.

Calculated shipping only.

Defines the unit for the weight.

You may need test different units. Different units are supported depending on your shop's location.

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.

Learn more about digital listings.

• 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.

Learn more about digital listings.

• 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.

The numeric ranking of where this listing should be featured on your shop page.

Leave this blank if you don't want to feature this listing on your shop page.

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

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

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

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.

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

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

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

Most sellers use personalization instead.

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.

Etsy seems to be moving away from styles in favor of category-specific attributes.

• 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.

Translations are available for all Etsy-supported languages.

If you want to provide your own translation you must provide the entire translation.

That means title, description, and tags must be translated.

Translations in the template will be look like this: {lang}_{column}.

For example the es_description = Spanish description.

Supported language codes: [nl, fr, de, it, ja, pl, pt, ru, es].

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 delete the ENTIRE 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 variations).

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 variations 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 variations from the listing before adding any variations.

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

Value must be True or False

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

A digital listing must always have at least 1 digital file

Value must be True or False

A unique Etsy defined code that helps categorize listings on Etsy

Use the category column instead.

Must be greater than or equal to 1