Migrating to Etsy’s Open API v3

We are working on exciting updates to Etsy’s Open API, and this guide is for existing API developers to learn about these changes:


This guide assumes you have an existing application and API key registered with the v2 API. If you do not, you can register a new app and start using Etsy’s Open API.

Purpose and benefits#

Our new Open API supports the following improvements over v2:

  • More accurate and usable reference documentation
  • Support for OAuth 2.0
  • A more approachable and up-to-date data model for our endpoints
  • Better developer support

Launch stages#

These stages in advance of the general release of Open API v3 and the sunset of v2 are meant to give you time to migrate, test, ask questions and give feedback about our new API.

Q4 2021Q3 2022Q2 2023
v2 will remain active. v2 may not receive all new feature upgrades.All newly created apps must use v3.Access to v2 endpoints are removed and v2 is officially sunset on April 3, 2023.
v3 will continue to get fixes and updates.Existing v2 apps can continue using v2.v2 endpoint calls will fail

New documentation#

We created the following documentation resources for the Open V3:

  • API reference contains details on all v3 resources and endpoints. It is generated from the API implementation, so it stays up-to-date with the functionality. If you have feedback or suggestions about our reference documentation, you can discuss it on Github Discussions.
  • API development guides (this site) replaces the current v2 documentation. We designed it to be more usable, complete, and easy to navigate. It covers topics like migration, essential endpoint information, and tutorials on certain use-cases.
  • In addition to our reference documentation, we published the details of our API publicly on Github in the Open API Specification (OAS) format.

Access to the new endpoints#

All users with an active application can make requests to the new endpoints.