Etsy Icon>

Code as Craft

Announcing Etsy's New API main image

Announcing Etsy's New API


Today I’m pleased to announce the pilot program of Etsy’s new read-write API, version 2.

For a few months now, we’ve made veiled references to “the next version of the API” in response to bugs and feature requests for our current API, but hadn’t made any official announcements or given a timeline. Behind the scenes, we’ve been working on a totally-new, revamped API that will eventually replace the current one.

Here’s a brief overview of some of the new features of this API:

Read-Write Support via OAuth The new API supports OAuth, a way of letting 3rd-party applications log into your Etsy account without requiring you to hand out your username and password (If you've ever used a Twitter client like Tweetie, you've used OAuth.)  This means that applications written on the new API will be able to interact with your Etsy account in totally new ways.

Built on Etsy's New Platform You may have noticed that the current API seems to lag behind the rest of by five or ten minutes--this is because we're caching the API results fairly heavily.  For the past year, we've been quietly upgrading the infrastructure behind Etsy piece-by-piece, and this process has finally caught up with the API.  The new API will not have a delay compared to the rest of the site, and will receive bugfixes and updates on a regular schedule.

New, Cleaner Interface We're doing away with the "detail levels" of the old API in favor of a new interface that lets you specify which fields and child objects to include with every request.  For instance, you'll be able to include images within a listing, listings within a shop, or the user who owns a shop within it.  You'll also be able to filter out fields that you don't care about, which will keep the size of your requests at a minimum.  This is much more flexible than the old "low, medium and high" system.

We're calling this a "pilot" because not everything is finished yet.  To start off with, we'll be opening the beta up to a small group of testers.  The top users of the current API will be included, as will everyone who's already written in asking to become a beta tester.  Then, we'll get to work fixing the bugs that are found and adding new features.  Every time we add new features to the API, we'll open it up to a few more beta testers.

Here's what you'll find in the pilot API:- OAuth support

  • Basic view of users, listings, shops and favorites
  • Ability to add and remove favorite users and listings
  • Inclusions (specifying which linked objects to return in results)
  • No delay compared to Etsy site
  • Basic keyword search support

Here's what you won't find in the pilot (but that we're working on:)- Advanced Search support

  • Filtering of fields (mentioned above)
  • Resources other than those named above
  • Add to cart / upload listings / other "write" methods

In addition, the new API won’t be backwards-compatible with the current API. The current API will remain online for the duration of the beta phase. Once the new API launches, the current API will remain online for six additional months. This will give you plenty of time to upgrade your applications to the new API.

If you’d like to become a beta tester, send an email to We’ll hand out API keys on a first-come, first-served basis.

We hope you’re as excited as we are!