3.0.0 General Release 2026-03-24

ListingVideo_Upload Bug Fix and Extended Functionality

Fixed bug where the ListingVideo_Upload endpoint would throw a 500 when attempting to associate an existing video to a listing.
Increased functionality of ListingVideo_Upload endpoint to support associating existing listing videos to other listings owned by the user.

Incorrect Image Ranking Bug

Fixed bug where multiple ListingImage_Upload requests in a short period of time resulted in duplicate image rankings.

Draft, Digital, Made to Order Listing Bug

Fixed bug where draft, digital, made_to_order listings created via the API could not be activated via the API

Correct Error Code in ListingVideo_Upload

Fixed issue where a unsupported format error in ListingVideo_Upload was incorrectly reported as a 500 instead of a 400

3.0.0 General Release 2025-10-24

Rate Limit Retry-After Header Correction

Previously, clients hitting their daily rate limit quota might have received an invalid value in the Retry-After header. This has been corrected. Clients who have exceeded their daily rate limit will now receive a valid Retry-After header value, correctly indicating when they can retry their requests.

3.0.0 General Release 2025-10-14

Documentation Type Fixes

There was an issue with our documentation where fields marked as an enum in example endpoint reponses were always typed as a string.
Our documentation now correctly marks the following enum fields as integers:

• holiday_id enum field in getHolidayPreferences and updateHolidayPreferences is now documented as an enum of integer
• type enum field in createShopShippingProfileUpgrade, getShopShippingProfileUpgrades, deleteShopShippingProfileUpgrade, and updateShopShippingProfileUpgrade is now documented as an enum of integer

Officially Deprecated Endpoints

The three endpoints marked as deprecated, getListingImageDeprecated, getListingImagesDeprecated, and updateListingDeprecated have been deleted from the codebase and now return a 404 Not Found as a response. Previously, they returned a 301 Moved Permanently.

3.0.0 General Release 2025-10-08

Transition to Processing Profiles

As part of the transition to Processing Profiles, the following updates have been made:

createShippingProfile

The input fields min_processing_time and max_processing_time are now optional and no longer affect stored data. These fields, along with processing_time_unit, are scheduled for removal in Q1 2026. Developers are encouraged to stop sending these fields immediately. A 30-day deprecation notice will be issued prior to their removal.

ShopShippingProfile

The fields min_processing_days, max_processing_days, and processing_days_display_label have been removed from the ShopShippingProfile response object.

Affected Endpoints:

• createShopShippingProfile
• getShopShippingProfile
• updateShopShippingProfile
• Anywhere includes=Shipping is available

3.0.0 General Release 2025-10-02

Bugfix for Receipts response

• Fixed an issue where the shipping cost for an OpenAPI order is not accurate if the buyer is a member of Etsy's Loyalty program (Etsy Insider)

Bugfix for OpenAPI Retry-After header

• Fixed an issue where clients would receive an inaccurate retry-after header value on 429 QPD rate limit violations.

3.0.0 General Release 2025-01-06

Bugfix and change in behavior for updateListing endpoint

• Fixed an issue where digital, draft, and made-to-order listings created via the API previously could not be updated to active using the updateListing endpoint.
• The updateListing endpoint will now throw a 400 when updating a digital, draft, and non-made-to-order listing missing an associated downloadable file with the following response:

  "error": "This digital listing cannot be activated. Please upload a file or associate an existing file to download with this listing."

3.0.0 General Release 2024-11-20

Fulfillment-related changes in Canada

For Personal Keys

• Going forward, new personal keys for shops in the Canada will no longer be able to access createReceiptShipment or address fields (formatted_address, first_line, second_line, city, state, zip, country_iso) in getShopReceipt, getShopReceipts, and updateShopReceipt
• Existing personal keys will retain their existing access

For Commercial Keys

• New users (sellers) located in the Canada will no longer be able to use functionality in commercial-key applications based on createReceiptShipment or address fields (formatted_address, first_line, second_line, city, state, zip, country_iso) in getShopReceipt, getShopReceipts, and updateShopReceipt unless that Commercial Application is an Etsy Preferred Partner or is in an approved category
• Existing sellers using a Commercial Applications will retain their access to createReceiptShipment

For more information, please see these help articles:

• How to Use a Third-Party Provider to Ship Your Order
• New Shipping Partners To Help You Manage and Ship Orders

3.0.0 General Release 2024-10-21

Fulfillment-related changes in the United States

For Personal Keys

• Going forward, new personal keys for shops in the United States will no longer be able to access createReceiptShipment or formatted_address in getShopReceipt, getShopReceipts, and updateShopReceipt
• Existing personal keys will retain their existing access

For Commercial Keys

• New users (sellers) located in the United States will no longer be able to use functionality in commercial-key applications based on createReceiptShipment or formatted_address in getShopReceipt, getShopReceipts, and updateShopReceipt unless that Commercial Application is an Etsy Preferred Partner or is in an approved category
• Existing sellers using a Commercial Applications will retain their access to createReceiptShipment

For more information, please see this help article: How to Use a Third-Party Provider to Ship Your Order

3.0.0 General Release 2024-08-01

A few of ShopReceipt’s fields are now nullable. These include:

• first_line
• second_line
• city
• state
• zip
• country_iso

The impacted endpoints are:

• createReceiptShipment
• getShopReceipt
• getShopReceipts
• updateShopReceipt

Previously these fields would return an empty string if the request was not authorized to access the data, now the field will not be present in the response if the request is not authorized.

No changes were introduced on how access is determined.

3.0.0 General Release 2024-07-24

As part of the announcement today that sellers can customize their holiday processing schedule, we have released 2 new endpoints:

• getHolidayPreferences
• updateHolidayPreferences

Note: this new functionality is currently only supported in the US and Canada.