The Etsy API allows developers to create apps that create and manage listings in a member’s shop, analyze sales history and feedback, and control shop appearance.
This page referrs to resources, fields, and assocations. Please refer to API Basics for descriptions of these terms.
The Etsy API allows apps to create listings in the Etsy marketplace. For full information on listings and related resources, please see Merchandising > Listings.
Sellers on Etsy can use templates to specify common payment and shipping options on listings:
PaymentTemplatespecifies payment options; a shop can have multiple PaymentTemplate records.
ShippingTemplaterecords specify shipping optionsr. Unlike PaymentTemplate, each ShippingTemplate has one or more
ShippingTemplateEntrychildren. Each child record specifies the shipping price to a different country.
In the above diagram, the dotted lines show how PaymentTemplate and ShippingTemplateEntry resources are copied to ShippingInfo and ListingPayment entries during listing creation. Once these resources have been copied, the link to the original template is lost (which means that editing a template does not change all of the listings created with that template.) Both of these template resources can be specified by ID when creating a new listing using
The Etsy API gives you access to customize a member’s shop in several ways:
- Each Etsy shop has a
ShopBannerimage that displays on shop pages. This can be changed with
- Etsy shops can be devided into one or more
ShopSections. Buyers can browse all the listings in a shop, or just the listings in a section.
- Finally, all Etsy members have an
Avatarimage as part of their profile. This displays on shop pages, as well.
In addition, the shop’s description, policies and other information can all be edited on the
Sales and purchases on Etsy are divided into three main resources: Orders, Receipts and Transactions:
Orderrepresents all the items in an Etsy member’s shopping cart at the time of checkout (note that the Etsy.com site exposes only one combined cart; while the API exposes multiple carts, one per seller.) Order records belong to the buyer, and cannot be accessed by the seller.
- At checkout time, a buyer’s order is divided into one or more
Receipts, one per seller. Each receipt represents a payment made by a buyer to seller for one or more listings. Receipts can also be used to leave message from the buyer or seller, and have flags for payment a shipping status.
Transactionrepresents the sale of a single Etsy listing. Each receipt is divided into one or more transactions. Because Etsy listings may be renewed and edited after purchase, the transaction contains a "snapshot" of the listing at the time of purchase.
- Using the
Listingassociation on transactions, apps can access the purchased listing. However, for any given transaction, there’s no guarantee that the original listing will still exist on Etsy, nor that it will be the same as at the time of purchase.
Receipts are doubly-associated with users. The
Buyer association points to the member who made the purchase; the
Seller association points to the member who made the sale. Receipts are also associated with a
Country record, which indicates the country to which the items will shop.
Etsy has a system called
Feedback that allows members to leave comments for each other in reference to transactions on Etsy. Each feedback record has a score (-1, 0 or 1) that is used to calculate a member’s feedback score. The basic structure of feedback records is this:
Each transaction can have up to two feedback records, one left by the buyer for the seller, and one left by the seller for the buyer. Feedback is optional; so not all transaction will have feedback records (although most will.)
Because feedback can indirectly expose an Etsy member’s purchase history; there are privacy rules concerning which fields can be seen in the API. See Feedback and Privacy Settings for details.
Each feedback record has an author, a subject, a buyer and a seller. The author is the member who left the feedback, and the subject is the member who received it is the subject. The methods
findAllUserFeedbackAsSeller will query feedback for any given member. In order to determine the context of a feedback record, you’ll need to examine the
Seller associations. The following is an example of a feedback record left by a buyer for a seller:
Note that Author and Buyer both point to the same user, and that Subject and Seller both point to a different user. The next example is feedback left by a seller for a buyer:
In this example, Author and Seller both point to the member making the sale, and Buyer and Subject point to the member who made the purchase.
Etsy allows sellers to submit tracking codes for their sold orders. This functionality is exposed in the API via the
A successful call to
submitTracking will send the buyer a shipping notification email.
This email tells the buyer that their order shipped, and displays the tracking code, along with a link to view tracking events
Tracking codes may not be submitted for an order where a shipping notification email has already been sent. Thus, at most one tracking code can be submitted in this manner.
If the order has not already been marked as shipped, a successful call to
mark the order as shipped. Note that a tracking code may be submitted for an order that has already been marked as shipped, as long as
no shipping notification email has been sent.
Let’s take a look at the parameters to
tracking_code is the alphanumeric tracking code provided by the mail carrier.
carrier_name is the mail carrier name. We have three levels of support for carriers.
The carrier name will be viewable on the shipping notification email sent to the buyer for all levels of support.
|Support Level||Tracking Events Viewable on Etsy?||Tracking URL Generated?|
If an Etsy recognized
carrier_name is not used, we will default to the unsupported level.
Below is a table of carrier names and their corresponding values that we will recognize in the
|Deutsche Post DHL||
|Correos - Espana||
|LA POSTE - ENVOI EN FRANCE||
|LA POSTE - ENVOI A L'ETRANGER||
|Israel Postal Company||
|Posten AB - Sverige||
|China Post - EMS||
|CTT Correios de Portugal||
send_bcc is true, we will email the seller a copy of the shipping notification email that was sent to the
A successful call to
submitTracking returns a
shipments field of the
Receipt will be an array of one
ReceiptShipment object. If a fully or partially supported
was supplied in the call to
tracking_url field of the
will be populated.