eCommerce API Design with the Etsy API

By Brad Scharmann in GET/technical Posted Mar 30, 2015

When interacting with the various eCommerce solutions and their APIs it is not uncommon to encounter a few standards as it pertains to resources. The concepts of Orders, Products and Customers seem to exist across the board, albeit in varying capacities.

etsy-banner-1920x540 These resources exist for a reason, as they provide insight and relevant details pertaining to the operation of a given eCommerce store. One eCommerce solution that has chosen not to fit this mold is Etsy, whose API can be both overwhelming and confusing. Let’s dive in and see where these differences lie.

I think it’s important to point out that Etsy, unlike most other eCommerce solutions we work with, is a representation of not just one shop but millions (billions????) of shops. This forces a mixture of authorized and unauthorized calls to retrieve information about Etsy as a whole in addition to information about a specific shop, and also creates confusion. Perhaps partitioning the API around this idea would provide more clarity. While there are hints of this with listings and receipts (Etsy’s products and orders, respectively), the current solution is neither clear nor intuitive. A fully functional authorized shop API can and should exist at the /shops nested endpoint, with access to industry standard resources. Current development on v3 of the Etsy API points towards this structure being adopted, though at the time of this writing there is no timeline for its release.

Etsy has split up the common “Order” into two distinct concepts: Transactions and Receipts. Transactions Etsy API integrationrepresent the sale of an individual item and Receipts are collections of transactions from a single purchase. When developing our own Etsy integration, we decided to choose Receipts as the best representation of what an order truly is.

Inherently a receipt did not include detailed transaction information (such as which products were purchased), though thankfully Etsy has a way to include this. We have chosen to exercise our rights and include all transaction information on every call for receipts. Unfortunately, querying past order information is all you can do from the API, and there is no way to create or update an order.

The one resource which has CRUD operations built around it is Products (Listings in the Etsy API). There are two ways to query listings via the API, one returning the entire catalog of listings for all of Etsy, the other narrowed down by Shop. To be consistent with Cloud Elements’ other eCommerce integrations, we have chosen to map the narrowed down listings to our products endpoint. The implementation for listings, as stated previously in this article, should serve as the example for other shop specific resources such as receipts (orders) and customers.

Speaking of customers, which is widely known as the third pillar of eCommerce API design, we find that this idea is not represented in Etsy’s API at all. You can query the generic bank of all Etsy Users, but without expensive follow-up queries there is no easy way to generate a list of users who have purchased from a specific shop. Just from looking at eCommerce API convention we can assume that this would be useful information. If not, all the Shopify’s, WooCommerce’s, Bigcommerce’s and Magento’s of the world have really led us down the wrong path (all of their API’s in some way support orders, products and customers).

Let’s take a step back. I think it is important to note we are being a bit harsh with the Etsy API while trying to fit it into a nice tidy little box that we have built. Clearly they designed it with their own business interests in mind, business interests which differ from other eCommerce solutions out there. That being said, it is my opinion that the partition for working with Etsy as a whole versus individual authorized shops could be more clearly and distinctly denoted. In addition, they should look to adopt some of the conventions we have seen from other eCommerce API’s as it relates to resources. Hopefully some of that purported $300 million dollar IPO will go towards development of their v3 API.

Try Etsy!