Getting started with Shop Uploader

Learn how to use Shop Uploader to update, create, and manage Etsy shops.

What is Shop Uploader?

Shop Uploader helps you create, update, and export your Etsy product data.

The Shop Uploader workflow is driven by templates. You export into templates, update your data within templates, and upload templates to create listings and make changes. The templates provide a consistent structure to your data and allow Shop Uploader’s various systems to understand how to handle your requests.

This is important because Shop Uploader doesn’t house your product information. We don’t ask you to upload all your data to our platform and then work within the platform to perform all your tasks. We leave you in full control over your data and take no ownership over that process. We operate more like a shipping company — but for product data — providing a way to package, transfer, and receive your data.

Since templates are the core of Shop Uploader, the rest of this guide will explain how they’re organized and why they’re organized that way.

If you’re familiar with other bulk uploading tools, and ready to jump right in, read this section: Shop Uploader templates are different than other platforms. Then, there are guides for each task you want to perform:

Now, let’s talk about templates.


Shop Uploader templates are the interface between your data and our systems. The template allows our system to understand your product data — without a Shop Uploader template, nothing works.

You can create Shop Uploader templates in two ways:

  • The template generator.
  • Exporting your existing listings into a Shop Uploader template.

First, we’ll go over how the columns are organized, then we’ll take a look at the rows and how to structure your product data.

Columns and column sets

Here’s how the columns work:

  • The first row of the template contains headers for each column.
  • The columns are grouped into sets.
    • Generally, column sets at the beginning of the template are the more important day-to-day information, while platform-specific data is deeper in the template.

At this point, you might want to generate a demo template and take a look around. The demos will showcase all the column sets. When you create your own templates, they will only have the column sets relevant to you, so don’t be surprised if they don’t look the same.

These are the column sets you are going to find in all Shop Uploader templates:

  1. Identifiers
  2. Marketing copy
  3. Pricing and inventory
  4. Category attributes
  5. Images
  6. Shipping (or digital files)
  7. Core details (who, what, when)
  8. Controls

Column sets refer to sections of product data. So, instead of diving in and explaining each column set, first I want to discuss how to structure your product data in the template rows. I will explain each of the column sets afterwards.

Rows and products

In Shop Uploader templates, each row is a product. What exactly that looks like is a little different depending on whether you have variations, if it’s a physical or digital listing. But just remember: 1 row is always 1 product.

Each row in the template is a product:

  • With variations, that means each row is a product variation.
  • Without variations, that means each row is a single-product listing.

Let’s quickly define these keywords to make sure everyone’s on the same page:

  • Product: The actual item for sale. This is what ships to a customer (or is downloaded).
  • Listing: The advertisement that lists the product(s) for sale.
  • Variation: A product with sibling products each only varying by some small aspect, such as color or size.

So, each row is a product. Got it. What about listings and variations?

Each row is also either a listing or a variation. That’s because every listing either contains 1 product or more than 1 product. In a Shop Uploader template that looks something like this:

parent_sku sku title price quantity
mysku1 My first listing 12.95 104

This is a single-product listing. 1 row = 1 product = 1 listing.

parent_sku sku title price quantity
psku1 mysku1 My first listing 12.95 504
psku1 mysku2 13.95 124
psku1 mysku3 14.95 257

This is a listing with variations. 1 row = 1 product = 1 variation.

In Shop Uploader templates, you only need to provide listing data on the first row of each listing. Listing data like title and description cannot change per-variation. So, Shop Uploader is just going to parse that data from the first row and apply it to the entire listing.

Unlike many other platforms, you can provide all the data on every row — do whatever’s easiest for you.

You probably notice that in the above example, we’re using a parent_sku to create the variations. Since each row is a product, there are no special rows for parents or anything like that. The parent_sku is only a string of text that identifies which rows should belong together. Same parent_sku, same listing.

Next steps

At this point, you know the basics of templates, column sets, and structuring product data into rows. The rest of this guide will expand on these concepts.

Not everyone cares about those details right now.

For those of you looking for what’s next:

Next, we’ll quickly discuss each of the main column sets.

Column sets

Picking up where we left off, this section will cover all the primary column sets. Depending on the complexity of your products and what data you want to upload, your templates are going to look different. These column sets are going to be in most templates.

Column set: Identifiers

Identifiers are unique pieces of data that differentiate between listings and products. These columns live at the very beginning of the template. They’re the most important columns, describing what products and listings even exist.

listing_id parent_sku sku

Column set: Marketing copy

Marketing copy is industry lingo for “words we write to make people buy our stuff.”

Title is the really important one. Little is shown to potential customers before they actually click on a listing. Titles are, and they’re also the most human-readable way to differentiate between listings — that’s why this section is #2 in the template.

title description

Column set: Pricing and inventory

Pricing and inventory are is most important data for product management. That’s why it’s the first column set after the columns that identify/differentiate between the products themselves.

price quantity

Column set: Category attributes

Category provide the highest-level classifying data about a product. This is the first and most important column set providing product details. The category defines what section of the store your listings belong in, the attributes describe the category-specific information about your products.

Each category supports different attributes. That means every template will have different columns depending on which categories are included. Shop Uploader differentiates these special columns by prefixing each one with an underscore (_). We refer to these as simply the _underscore_columns instead of “category-specific attribute columns.”

All the _underscore_columns are optional.

category _primary_color _fabric _pattern _holiday

Column set: Images

Images showcase your products, and are probably the most important thing to get right if you want to attract customers. So, they’re the next section in the template.

All media in Shop Uploader is uploaded by URL. You have to provide a URL directly to the raw file so that Shop Uploader can download the data and upload it to Etsy. That means no previews or password-protected links (unless you use one of our direct integrations with Google Drive or Dropbox).

Since they’re a little complicated, images have their own guide.

image_1 image_2 image_10

Column set: Shipping

Shipping can either be simple, free or fixed-rate shipping, or it can be complicated. If it’s simple, you just need to connect your shipping profile and return policy.

Calculated shipping requires the listing dimensions — a set of dimensions that doesn’t really make sense… Etsy’s calculated shipping applies to the entire listing and all variations use the same weight and dimensions.

If you’re selling digital products, the entire shipping section will be omitted from your template.

shipping_profile_id return_policy_id

Column set: Digital files

Digital files are the product of a digital listing. All the digital files will be immediately downloadable upon purchase. The digital files are provided by URL, just like the images, but you also must provide the filename. On Etsy, the files will be named whatever you specify in digital_file_name_1, etc., regardless of the original filename.

digital_file_1 digital_file_2 digital_file_name_1 digital_file_name_2

Column set: Core details

At this point, we’re really in the nitty-gritty details of a product listing. This section is all the required platform-specific information. They all required columns and they’re strangely interdependent. Luckily, for most shops, you can define these core details once and reuse them for all other listings.

Shop Uploader expects TRUE or FALSE for this kind of toggleable (boolean) data.

type who_made is_made_to_order is_vintage year_made auto_renew is_taxable is_supply

Column set: Controls

The final column set is the Shop Uploader controls. Most importantly, the action column. These columns describe how you want Shop Uploader to process your data.

action listing_state overwrite_images

Where to learn more about each column

If you are ever wondering about a specific column — what’s allowed, what’s required, what the heck even is it? — the best place to look is the template documentation. That is the definitive place for everything about the templates. It will always be the most comprehensive and the most up-to-date.

If you’ve made it this far, congratulations, you’re one of the few 😅! Now that you have a grasp on the organization of the template itself, let’s talk about how to add product data.

Shape of data

Note: If you don’t have variations, this section is irrelevant to you. Also, this section is a little technical and mostly is directed at people familiar with uploading to other platforms like Shopify or Amazon.

If you’re familiar with other platforms, Shop Uploader templates will look a little different because of the shape of product data.

Shop Uploader templates use a normal or uniform data shape. That means there are no parent rows, listing headers, or whatever else they’re called. Remember, each row is a product. That means each row can look the same and have all the same data.

The opposite of a normal data shape is a jagged data shape. Something like this:

id title sku price quantity
1234567890 My listing
vari1 11.50 22
vari2 11.50 22
vari3 11.50 22
2345678901 My other listing
zvari1 21.50 12
zvari2 31.50 34

If you’re familiar with Amazon or Shopify, this is what you’re used to.

In Shop Uploader, instead, it looks something like this:

id title sku price quantity
1234567890 My listing vari1 11.50 22
1234567890 My listing vari2 11.50 22
1234567890 My listing vari3 11.50 22
2345678901 My other listing zvari1 21.50 12
2345678901 My other listing zvari2 31.50 34

Each row can have all the data

Or it can look like this:

id title sku price quantity
1234567890 My listing vari1 11.50 22
1234567890 vari2 11.50 22
1234567890 vari3 11.50 22
2345678901 My other listing zvari1 21.50 12
2345678901 zvari2 31.50 34

Only the first row needs the listing data.

The fact that Shop Uploader even supports two options is a direct function of the data shape. With jagged data, this is impossible. The main benefit of our normal data shape is that it allows you to work in whichever paradigm is best for you: listing-by-listing or variation-by-variation.

Normal data shapes are faster to manipulate and make building automations simpler. The only reason other platforms use jagged data is to force you to send the minimum-necessary data and it makes the difference between listings and variations more explicit. We prioritize simplifying your workflow and improving data-management ergonomics.

The most powerful
tool for Etsy sellers