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 referrs to resources, fields, and assocations. Please refer to API Basics for descriptions of these terms.
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:
Listingis 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
findAllShopListingsActiveto query the currently available listings for a shop.
- Each shop can optionally have one or more
findAllShopSectionsto find all the sections for a given shop.
- Each listing can have up to five images, uploaded by the seller. Use either the
Imagesassociations of Listing to retrieve these images. You can also use the dedicated
- Each listing will have one or more
ListingPaymentsdescribing the payment methods accepted by the seller.
ShippingInforecords describe the locations that the seller will ship to, and the cost. Each shipping info record is associated with two
Countryrecords 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 cronological 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
Etsy members can tag listings or entire shops as favorites:
FavoriteListingis a linking resource that connects an Etsy member to a listing they're favorited. This resource is typically used with the
Listingassociation to pull the actual listing being favorited.
FavoriteUseris a linking resource that connects and Etsy member to another member whose shop they've favorited. (Note that although the Etsy.com site referrs to "favorite shops," the link is actually made between users.) Use the
TargetUserassociation 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
findAllUserFavoriteListingsto pull favorite listings for an Etsy member, and
findAllListingFavoredByto find all members who've marked a listing as a favorite.
- For users, user
findAllUserFavoriteUsersto pull favorite users for an Etsy member, and
findAllUserFavoredByto 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.
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.
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
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