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 refers to resources, fields, and associations. 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 options. 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 divided 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 and 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 ship.

Feedback

Etsy has a system called Feedback that allows members to leave comments for each other in reference to transactions on Etsy. It's important to note that the API reflects our previous feedback system, so 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 our Terms of Use 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

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

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.