Whats going on?

The online sales platform Etsy is transitioning to a new version of their API and sunsetting the current version in Q3/Q4 2022. The changes were significant enough that it was impossible to update the existing integration and we had to build a completely new one.

Table of Contents:

  1. What does this mean for me?

  2. What changed?

    1. Choose what product types to import

    2. Turn off order shipped notifications

    3. Automatic product re-listing

    4. Etsy variation management & duplicate listings

    5. Unmanaged Stock or Price listings

  3. What still doesn't work.

    1. Getting refunded order info

    2. Customs information, Tariff number

    3. Domestic & global pricing

    4. De-Linking variation images

    5. Missing apostrophes ' ' & Quotation marks " ":

  4. How to move to the new integration?

What does this mean for me?

Etsy will stop supporting their old API sometime in Q3/Q4 2022, at which point the old Etsy integration will simply stop working. You need to re-integrate your Etsy store using the new method to avoid any syncing issues between your store and Multiorders.

What changed?

Because we needed to create a new integration anyway, we took this as an opportunity to add new features as well as address some of the ongoing problems with the current Etsy integration. We have made many critical changes, so please read the following information carefully.

Choose what product types to import:

In the past we would only import Active listings, now you will be able to choose what type of products you want us to import. These settings can be changed both during the initial integration and after.

Turn off order shipped notifications:

When shipping orders through Multiorders the Etsy option for "Email me a copy of this notification" would always turn back on. We have now added an additional settings to the integration where you can turn this off.

Automatic product re-listing:

Since stock can only be changed through Multiorders, dealing with sold out listings on Etsy is always a huge pain. The listings need to be either located in Multiorders to relist, or relisted on Etsy and then get their stock update on Multiorders. To make this simpler we have added an auto-relist option, if a product is sold out on Etsy and you increase it's stock back to a positive value, the product will be relisted on next inventory sync. This feature can be turned on via the integration settings.

Etsy variation management & duplicate listings:

We have left the most complicated and important changes for last. I will now go into detail on why that change had to be implemented, if you don't care about the "why" you can skip to the next paragraph.

For inventory management to work with an app like Multiorders, listings from sales channels like Etsy must contain a unique, never changing identifier. This is how Multiorders knowns which product to update or which product has been updated on Etsy. For some reason Etsy only has these unique identifiers for Listings as a whole and when we encounter variation info, there is suddenly nothing to relate the individual parts with. Because of this, there has been a prevalent issue of Etsy listings duplicating within Multiorders for seemingly no reason, sometimes after a stock change, sometimes the price.

The Etsy team's comment was this:

The inventory system does work as intended. We are aware that this can be challenging because the product ids and offering ids are changed each time you save the inventory. However, this is by design. Every time the inventory is updated, a new set of inventory data is created and the previous set of data is archived for posterity and tracking purposes. There is no single key id for any given product in an inventory. We recommend using SKUs for each product/variation.

We personally think that every product should have a unique SKU, but Etsy neither forces users to input any SKU info, nor do they force it to be unique. The end result is that there is nothing that can be done normally and we are forced to implement measures on our own.

To prevent the issue of duplicating listings you must have unique SKU's for each product variation. You can have identical SKU's across multiple listings, you just can't have missing or duplicate SKU's within the same listing (although we don't recommended duplicate SKU at all for general inventory management purposes). If your configurable product has no unique SKU per variation, we will not import that product until it is fixed. This is the only way we can prevent any duplicating listing issues.

Unmanaged Stock or Price listings:

Most of you are aware of the Listing management option that let's you manage only quantity or only price for your product variations, written as "Prices vary for each primary colour" or "Quantities vary for each primary colour".

If you don't select the option to manage price or stock for the variations, the Etsy platform still creates the variations, it just doesn't show them to you. This causes problems on our end because we would see all of those variations and users with this enabled will often get way more products imported into Multiorders than they expected, as well as get errors like this when updating stock or price:

"data":"quantity must be consistent across all products"

With the new update we are implementing a similar system as Etsy to prevent these errors as well as hundreds of useless variations, but it comes with a few limitations.

I will try to detail each combination of options and explain what you can expect, but before that I immediately need to say this, If your variations have no Quantity management turned on, we will not import them. Those types of variations are incompatible with the system and will be ignored.

= Option 1 - Nothing is managed:

If you have this, we will import absolutely nothing, because you would have no unique SKU's and no stock control.

= Option 2 - One variation is fully managed:

We will only import the first variation options since nothing is managed for the second one.

But there will be a slight visual oddity with these listings. The system expects to create a full list of products from the variations so in it's naming scheme it is still building the products on Multiorders as "Product Title" + "Variation 1, Option 1" + "Variation 2, Option 1" and ultimately ends up looking like this.

Each variation has a "(Secondary Color - Black)" attached to the end of it. This is purely visual and has no effect on the actual listing. Your orders will be ok as well. You will still be able to see what the customer has chosen, even if those variations do not import into Multiorders.

= Option 3 - SKU's are not managed for variations:

We will import nothing because due to the new rules to prevent listing duplicates, all variations must have unique SKU's within the same listing.

= Option 4 - Everything except the price is managed:

In this scenario, we would generate all variations, but there is a problem. Changing the price for one variation will update your listing, but you will still have several other variations within multiorders with different numbers. It is recommended that you update the price to match on all variations. The reason we allow for the variation to be generated is because we consider the price to be less critical and managed quantity products MUST be imported.

Alternatively you could update the products price from Etsy and then press "Import Now" on your integration to get those imported into Multiorders instantly.

What still doesn't work.

While these are things we wanted to add, they are either not feasible at the moment or simply not possible with the current Etsy API.

Getting refunded order info:

In the past when we imported order info, we would also get small piece of data called "adjusted_grandtotal". This would tell us the difference of the order total which would indicate that a refund had happened and we could adjust the order total accordingly. The new Etsy API does not have this field anymore and to get this info we would need to check every order individually, during every order import, trying to find any change in the refund history. If we did this we would end up with significantly longer import times as well as reach other API limits preventing us from importing anything at all. This feature has been requested to be put back by the Etsy developer community and it may still return.

As of writing this guide, the official Etsy statement is this:

We will look into feasibility of adding an adjusted grand total to the receipt.

Customs information, Tariff number:

Also known as an "HS Code".

Since we have a place to store this number in Multiorders, we intended to import it from Etsy when available. Unfortunately this is not possible via the Etsy API and probably never will be.

As of writing this guide, the official Etsy statement is this:

This has been requested before. Unfortunately, it is not something we plan to add to the OpenAPI at this time. Sorry we can't provide this for you.

Domestic & Global pricing:

The fairly new feature allowing you to enable different prices for your listings is not yet supported by the Etsy API.

As of writing this guide, the official Etsy statement is this:

Thanks for bringing this up. This is certainly something we have on our roadmap for OpenAPI. I don't know when it will be handled, but we hope to get to it soon.

If you turn this feature on, Multiorders will only import the "Global" pricing. There is also a known bug where the "Domestic" prices are wiped during a standard price update via Multiorders. Whether this will happen or not is a lottery as we have seen different results on different accounts, the issue is not within Multiorders, but within the Etsy API. One more additional note that we would like to make is that once the API is supported, we will still only import one price into Multiorders as the system simply has no method of supporting this feature, but we won't overwrite the other price during update at least.

De-Linking variation images:

From our testing while developing the new integration we did not experience image delinking from variations.

But we did not implement any additional methods to prevent it either, because we could not find anything within the Etsy API for this. This bug also rarely happens with the current integration and it appears to be up to the whimsy of the Etsy API whether this will happen or not. There is no official statement on this bug at the time of writing this.

Missing apostrophes ' ' & Quotation marks " ":

Due to the danger of these symbols causing problems in code, they are stored in an encoded format and are converted live on the storefront on Etsy, but when order and product info is returned to us via API we get the encoded version that looks like " &#39 > <. To avoid this showing up in address info or order info we simply sanitize the data and remove them. The downside of this is if you are using "" or '' to mark things like size for inches, your product titles are now missing this info and are harder to find via search.

How to move to the new integration?

Simply go to your Integrations menu find Etsy v3 option and connect your store again through there.

As for your old Etsy integration, since the v2 API is going to be active for a while, you either need to delete your old integration or if you want to keep your old integrations data, we could break the credentials so that no unwanted updates would go out. If you want to use this option, get in touch with us via the live chat.


Please be aware deleting your integration will remove all products and orders relating to this store, it will also break any Bundled items that we're built using these products.

Did this answer your question?