API Documentation

Seller Tools

Overview

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.

Listing Templates

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:

  • PaymentTemplate specifies payment options; a shop can have multiple PaymentTemplate records.
  • ShippingTemplate records specify shipping optionsr. Unlike PaymentTemplate, each ShippingTemplate has one or more ShippingTemplateEntry children. 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 createListing.

Shop Appearance

The Etsy API gives you access to customize a member’s shop in several ways:

  • Each Etsy shop has a ShopBanner image that displays on shop pages. This can be changed with uploadShopBanner.
  • 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 Avatar image 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 Shop resource.

Transactions

Sales and purchases on Etsy are divided into three main resources: Orders, Receipts and Transactions:

  • Order represents 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.
  • Transaction represents 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 Listing association 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.

Feedback

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 findAllUserFeedbackAsAuthor, findAllUserFeedbackAsSubject, findAllUserFeedbackAsBuyer and findAllUserFeedbackAsSeller will query feedback for any given member. In order to determine the context of a feedback record, you’ll need to examine the Author, Subject, Buyer and 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.

Tracking Codes

Etsy allows sellers to submit tracking codes for their sold orders. This functionality is exposed in the API via the submitTracking method.

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 (if applicable).

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 submitTracking will 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 submitTracking:

submitTracking Parameters

Name Required Default Type
tracking_code Y   string
carrier_name Y   string
send_bcc N boolean

tracking_code

tracking_code is the alphanumeric tracking code provided by the mail carrier.

carrier_name

carrier_name is the mail carrier name. The carrier name will be viewable on the shipping notification email sent to the buyer.

If an Etsy supported carrier_name is submitted, we will provide a tracking link in the shipping notification email. We will also display tracking updates for the shipment on Etsy (if the carrier is listed as "Trackable on Etsy").

Below is a table of carrier names and their corresponding values that we will recognize in the carrier_name parameter.

Supported Carriers
Carrier carrier_name Trackable on Etsy?
4PX Worldwide Express 4px Yes
ABF Freight abf Yes
ACS Courier acscourier Yes
APC Postal Logistics apc Yes
AeroFlash aeroflash Yes
Afghan Post afghan-post No
An Post an-post Yes
Anguilla Postal Service anguilla-post No
Aramex aramex Yes
Asendia USA asendia-usa Yes
Australia Post australia-post Yes
Austrian Post austrian-post Yes
Austrian Post Registered austrian-post-registered Yes
BH Posta bh-posta No
Bahrain Post bahrain-post No
Bangladesh Post Office bangladesh-post No
Belgium Post Domestic bpost Yes
Belgium Post International bpost-international Yes
Belposhta belpost Yes
Blue Dart bluedart Yes
BotswanaPost botswanapost No
Brunei Postal Services brunei-post No
Bulgarian Posts bgpost Yes
Cambodia Post cambodia-post Yes
Canada Post canadapost Yes
Ceska Posta ceska-posta Yes
China EMS china-ems Yes
China Post china-post Yes
Chronopost France chronopost-france Yes
Chronopost Portugal chronopost-portugal Yes
Chunghwa Post taiwan-post Yes
City Link city-link Yes
Colissimo colissimo Yes
Correios de Brasil brazil-correios Yes
Correios de Macau correios-macau No
Correios de Portugal (CTT) portugal-ctt Yes
Correo Argentino Domestic correo-argentino Yes
Correo Argentino International correo-argentino-intl Yes
Correo Uruguayo correo-uruguayo No
Correos - Espana spain-correos-es Yes
Correos Chile correos-chile Yes
Correos De Mexico correos-de-mexico Yes
Correos de Costa Rica correos-costa-rica No
Correos del Ecuador correos-ecuador No
Courier Post courierpost Yes
Couriers Please couriers-please Yes
Cyprus Post cyprus-post Yes
DHL Benelux dhl-benelux Yes
DHL Express dhl Yes
DHL Germany dhl-germany Yes
DHL Global Mail dhl-global-mail Yes
DHL Global Mail Asia dhl-global-mail-asia Yes
DHL Netherlands dhl-nl Yes
DHL Parcel NL dhl-parcel-nl Yes
DHL Polska dhl-poland Yes
DPD dpd Yes
DPD Germany dpd-de Yes
DPD Polska dpd-poland Yes
DPD UK dpd-uk Yes
DTDC India dtdc Yes
Deltec Courier deltec-courier Yes
Deutsche Post deutsch-post Yes
Direct Link directlink Yes
EC-Firstclass ec-firstclass Yes
Egypt Post egypt-post No
El Correo el-correo No
Elta Courier elta-courier Yes
Empost emirates-post Yes
Empresa de Correos de Bolivia correos-bolivia No
Estafeta estafeta Yes
Estes estes Yes
Estonian Post estonian-post No
Ethiopian Postal Service ethiopian-post No
Evergreen evergreen Yes
Fastway Australia fastway-au Yes
Fastway Couriers fastway-ireland Yes
Fastways Couriers South Africa fastway-za Yes
FedEx fedex Yes
Fedex UK (Domestic) fedex-uk Yes
First Flight Couriers first-flight Yes
Flash Courier flash-courier Yes
GATI-KWE gati-kwe Yes
GLS gls Yes
Ghana Post ghana-post No
Greyhound greyhound Yes
Guernsey Post guernsey-post No
Hay Post hay-post No
Hellenic Post hellenic-post No
Hermes hermes Yes
Hermes Germany hermes-de Yes
Hong Kong Post hong-kong-post Yes
Hrvatska Posta hrvatska-posta Yes
India Post india-post Yes
India Post International india-post-int Yes
Interlink Express interlink-express Yes
International Seur international-seur Yes
Ipostel ipostel No
Iran Post iran-post No
Islandspostur islandspostur No
Isle of Man Post Office isle-of-man-post No
Israel Post israel-post Yes
Israel Post Domestic israel-post-domestic Yes
Jamaica Post jamaica-post No
Japan Post japan-post Yes
Jersey Post jersey-post No
Jordan Post jordan-post No
Kazpost kazpost No
Korea Post korea-post Yes
Kuehne + Nagel kn Yes
La Poste la-poste-colissimo Yes
La Poste Monaco poste-monaco No
La Poste Tunisienne poste-tunisienne No
La Poste du Senegal poste-senegal No
LaserShip lasership Yes
Latvijas Pasts latvijas-pasts No
LibanPost libanpost No
Lietuvos Pastas lietuvos-pastas Yes
MRW mrw-spain Yes
Magyar Posta magyar-posta Yes
Makedonska Posta makedonska-posta No
Malaysia Pos Daftar malaysia-post-posdaftar Yes
Maldives Post maldives-post No
MaltaPost maltapost No
Mauritius Post mauritius-post No
Multipack mexico-multipack Yes
Nacex nacex-spain Yes
New Zealand Post new-zealand-post Yes
Nieuwe Post Nederlandse Antillen (PNA) nieuwe-post-nederlandse-antillen-pna No
Nigerian Postal Service nipost Yes
Nova Poshta nova-poshta Yes
OCA oca-ar Yes
OPEK opek Yes
OPT opt No
OPT de Nouvelle-Caledonie opt-nouvelle-caledonie No
Oman Post oman-post No
OnTrac ontrac Yes
PTT Posta ptt-posta Yes
Pakistan Post pakistan-post No
Parcelforce Worldwide parcel-force Yes
Poczta Polska poczta-polska Yes
Pos Indonesia pos-indonesia Yes
Pos Indonesia International pos-indonesia-int Yes
Pos Malaysia malaysia-post Yes
Post Aruba post-aruba No
Post Danmark danmark-post Yes
Post Fiji post-fiji No
Post Luxembourg post-luxembourg No
PostNL Domestic postnl Yes
PostNL International postnl-international Yes
PostNL International 3S postnl-3s Yes
PostNord Logistics postnord Yes
Posta posta No
Posta Kenya posta-kenya No
Posta Moldovei posta-moldovei No
Posta Romana posta-romana Yes
Posta Shqiptare posta-shqiptare No
Posta Slovenije posta-slovenije No
Posta Srbije posta-srbije No
Posta Uganda posta-uganda No
Poste Italiane poste-italiane Yes
Poste Italiane Paccocelere poste-italiane-paccocelere Yes
Poste Maroc poste-maroc No
Posten AB sweden-posten Yes
Posten Norge posten-norge Yes
Posti posti Yes
Postmates postmates Yes
Purolator purolator Yes
Qatar Post qatar-post No
RL Carriers rl-carriers Yes
RPX Indonesia rpx Yes
Red Express red-express Yes
Redpack mexico-redpack Yes
Royal Mail royal-mail No
Russian Post russian-post Yes
SDA Express Courier italy-sda Yes
SEUR Espana (Domestico) spanish-seur Yes
SEUR Portugal (Domestico) portugal-seur Yes
SF Express sf-express Yes
Safexpress safexpress Yes
Sagawa sagawa Yes
Saudi Post saudi-post Yes
Selektvracht selektvracht Yes
Senda Express mexico-senda-express Yes
Serpost serpost No
Singapore Post singapore-post Yes
Singapore SpeedPost singapore-speedpost Yes
Siodemka siodemka Yes
SkyNet Wordwide Express skynetworldwide Yes
Skynet Malaysia skynet-malaysia Yes
Skynet Worldwide Express skynetworldwide Yes
Slovenska posta slovenska-posta No
South Africa Post Office sapo Yes
StarTrack star-track Yes
Swiss Post swiss-post Yes
TA-Q-BIN Hong Kong taqbin-hk Yes
TA-Q-BIN Japan taqbin-jp Yes
TA-Q-BIN Malaysia taqbin-my Yes
TA-Q-BIN Singapore taqbin-sg Yes
TGX tgx Yes
TNT tnt Yes
TNT Australia tnt-au Yes
TNT Italia tnt-it Yes
TNT UK tnt-uk Yes
TTPost ttpost No
Thailand Post thailand-post Yes
Toll Global Express toll-global-express Yes
Toll Priority toll-priority Yes
UK Mail uk-mail Yes
UPS ups Yes
UPS Freight ups-freight Yes
USPS usps Yes
UkrPoshta ukrposhta Yes
Vanuatu Post vanuatu-post No
Vietnam Post vnpost Yes
Vietnam Post EMS vnpost-ems Yes
Xend xend Yes
YRC Freight yrc Yes
Yanwen yanwen Yes
Yemen Post yemen-post No
Yodel yodel Yes
Zampost zampost No
Zimpost zimpost No
i-parcel i-parcel Yes

send_bcc

If send_bcc is true, we will email the seller a copy of the shipping notification email that was sent to the buyer.

Return Value

A successful call to submitTracking returns a Receipt object. The shipments field of the Receipt will be an array of one ReceiptShipment object. If a fully or partially supported carrier_name was supplied in the call to submitTracking, the tracking_url field of the ReceiptShipment will be populated.

Your Developer Account