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 ample time to migrate, test, ask questions and give feedback about our new API.

v3 Alphav3 Betav3 General Releasev2 Sunset
TimeframeQ1 2021Q2 2021Q3 20212022
FunctionalityMany endpoints are proposals, callable but not functionalCore API functionality and essential documentation completeFull production functionality and stability, all documentation completeAccess to v2 endpoints is removed
PurposeValidate feature and functionality requirementsSolicit feedback to surface bugs and improvementsRelease for production useRetire v2 and set deadline for migration to v3
AccessDocumentation is public, endpoint access by approved developersAny developer can opt-in to access new endpointsPublicV2 endpoint calls will fail
Data model stabilitySignificant design changes likelyDesign changes possibleStable design

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 open an issue in Github.
  • 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.

Access to the new endpoints#

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

Report bugs or send feedback#

In addition to our reference documentation, we published the details of our API publicly on Github in the OpenAPI Specification (OAS) format. To report an issue or send us feedback on the API design, please open an issue in Github.