Merchandising

Overview

Etsy is a marketplace, and the Etsy API makes it easy to display listings either for an individual store, or across the Etsy marketplace as a whole. In addition, the Etsy API gives you access to an Etsy member's favorite listings, sellers, and recommended listings from our recommendation engine. Finally, using the Etsy API, you can add listings to a member's cart, and direct him or her back to Etsy.com for checkout.

This page refers to resources, fields, and associations. Please refer to API Basics for descriptions of these terms.

Listings

Items for sale on Etsy are called listings. Each Etsy listing has a number of associated resources, which taken as a whole, describe the entire item for sale:

• Listing is the main resource and contains the item description and quantity currently available.
• Each listing is indirectly associated with one Shop (note that the true association is made between users and listings.) Use findAllShopListingsActive to query the currently available listings for a shop.
• Each shop can optionally have one or more ShopSections Use findAllShopSections to find all the sections for a given shop.
• Each listing can have up to five images, uploaded by the seller. Use either the MainImage or Images associations of Listing to retrieve these images. You can also use the dedicated findAllListingImages method.
• Each listing will have one or more ListingPayments describing the payment methods accepted by the seller.
• ShippingInfo records describe the locations that the seller will ship to, and the cost. Each shipping info record is associated with two Country records describing the country of origin, and the destination country for the shipping record.
• Country records may be associated with a Region. The region is used to populate a number of shipping info records at the time that the listing is created. However, the data is completely denormalized, meaning that all of the relevant shipping information exists in the shipping info records. You may choose to collapse on the region record, or ignore it completely.

To search listings across all of Etsy, use findAllListingActive. By default, this method returns the most recent listings on Etsy in reverse chronological order. Search queries can be narrowed on any combination of: keywords, average color of main image, price, seller's location, tags, materials, and keywords. To search only within a given shop, use findAllShopListingsActive.

Favorites

Etsy members can tag listings or entire shops as favorites:

• FavoriteListing is a linking resource that connects an Etsy member to a listing they're favorited. This resource is typically used with the Listing association to pull the actual listing being favorited.
• FavoriteUser is a linking resource that connects and Etsy member to another member whose shop they've favorited. (Note that although the Etsy.com site refers to "favorite shops," the link is actually made between users.) Use the TargetUser association to pull the user being favorited.

The Etsy API allows you to query the favorites for a given member, as well as all the members who's marked a listing or another member as a favorite:

• For listings, use findAllUserFavoriteListings to pull favorite listings for an Etsy member, and findAllListingFavoredBy to find all members who've marked a listing as a favorite.
• For users, user findAllUserFavoriteUsers to pull favorite users for an Etsy member, and findAllUserFavoredBy to find all member's who's marked a user as a favorite.

Note that FavoriteUser is doubly-linked to user: the User association points to the user who owns the favorite, while the TargetUser association points to the member whose shop is being added as a favorite.

Recommended Listings

The Etsy API gives apps access to Etsy's recommendation engine. Because recommendations are tailored to a specific Etsy member, this requires OAuth access. Use getRecommendedListings to access a member's recommendations.

Once you've shown an Etsy member his or her recommendations, register the views with registerRecommendedListingViews. This prevents the same listings from coming up again in recommendations (which would be repetitive.) You might also want to give the user the option of rejecting the recommendations with registerRecommendedListingRejects. Not only does this prevent the listings from coming up again, it improves the quality of new recommendations.

Recommended listings are recalculated every 24 hours, so changes in recommendations will not show up immediately. Also, be aware that it's possible to exhaust a member's recommended listings, in which case you'll need to wait another 24 hours for new recommendations to become available.

Checkout

Using the Etsy API, apps can add listings to an Etsy member's shopping cart. Although the Etsy.com site exposes the member's cart as a single resource, it's actually a number of carts, with listings sorted by the shop selling them. (This is because Etsy transactions happen directly between the buyer and the seller, so payment must be made individually to each seller at a time.)

Cart is the main resource; an Etsy member will have zero or more carts, one for each seller. Cart resources are automatically managed; it's not necessary for apps to create the cart before listings can be added to it. Simply posting the listing ID to the member's cart with addToCart will create the cart as necessary. When a cart is emptied completely using removeCartListing, it will be automatically destroyed. Apps can also empty a full cart in one request using deleteCart.

CartListing is a linking resource that holds the ID of the listing in the cart and the quantity added. The listings field of the cart resource will contain an array of cart listings. To retrieve the actual Listings in the member's cart, use the association Listings.

In addition, buyers may apply a coupon code to the cart using updateCart. When in use, this will appear in the cart object as Coupon.