Open API v2 will be deprecated on April 3, 2023. Please begin transitioning to Open API v3 as soon as possible. As of September 29, 2022 all new apps will only be permitted to use Open API v3.

API Documentation

Listing

Overview

Listings on Etsy are items for sale. Each Listing is associated with a User, and with a Shop (Users own Shops.) Etsy Listings have a creation date, and are valid for approximately four months. Listings have a price and a quantity, and when they're sold out, the User must renew them before they can be sold again.

Listing States

The state field of Listings indicates whether a Listing is currently available for display on Etsy. Most of the time, you will only see Listings in the "active" state, but the following states may rarely appear:

State Can Edit Can Renew Meaning
active Yes Yes The Listing is currently for sale.
removed No No The Listing has been removed by its owner.
sold_out Yes* Yes The Listing has sold out. *Sold out listings can be edited, but active=true will only be honored if renew=true is also passed. Users will be billed for this action. Otherwise, the listing will remain in the sold_out state. Note that when editing a sold out listing, you will need to update the quantity to a value greater than zero.
expired Yes** Yes The Listing has expired. **Expired listings can be edited, but active=true will only be honored if renew=true is also passed. Users will be billed for this action. Otherwise, the listing will remain in the expired state.
alchemy No No Deprecated: Please ignore.
edit Yes Yes The Listing is inactive. (For legacy reasons, this displays as "edit".)
draft No No Draft listings are listings that have been saved prior to their first activation. The API can create draft listings, and also make draft listings active, but note that a listing in any other state cannot be moved to draft, nor can a draft listing be moved to any state other than active.
create No No The Listing is currently being edited by the owner (as part of the initial Listing creation.)
Deprecated: Please ignore.
private No No The owner of the Listing has requested that it not appear in API results.
unavailable No No The Listing has been removed by Etsy admin for unspecified reasons. Listings in this state may be missing some information which is normally required.

Searching Listings

By default, the method findAllListingActive returns all active Listings on Etsy, paginated by date. Use the optional parameters (such as keyword, min_price, etc.) to narrow these results. The sort_order and sort_on parameters can be used to change the order of returned results. Note that these parameters are only available when using sort options. Without sort options, they will be ignored (and Listings will be returned newest-first.)

The parameters translate_keywords and language may be used in conjunction with keywords to support non-English searches with findAllListingActive and findAllShopListingsActive. If language is set to a value other than en and translate_keywords is true, findAllListingActive will return results for keywords translated from the given language into English. For example, ?keywords=buch&language=de&translate_keywords=true will translate the term "buch" from German into English and search for listings that match the search term "book." If these listings have a German translation, the listing results will be returned in German.

To search within a shop, use findAllShopListingsActive.

Editing Listings and Bill Charges

Listings may be edited with the updateListing method. Note that the Etsy API will attempt to activate a Listing after every edit operation. This may result in charges to the user's Etsy bill. To edit an inactive Listing without activating it, pass the optional parameter state=inactive. Note that edit options that increase the quantity of a Listing will result in charges to the owner. It is the developer's responsibility to warn the user that such charges may occur.

To renew a Listing for another four months, pass the optional parameter renew=true. A Listing does not need to be expired to be renewed, however note that each renewal does not take the Listing's previous expiration date into account, so any unused time remaining on the Listing's old expiration date will be lost. Renewals will result in charges to a user's bill.

Translations

Data of some models in the API can be expressed in multiple languages. For example, a Listing's title and description can be translated into German or French. To access this data in the API you can use the language parameter. Like this /listings/12345?language=de. For more information about this look at Working with Translations.

Categories and Tags

Categories are no longer the first three tags of a Listing. Category is a first-class resource, with its own primary key ID. When calling createListing, you must pass a category_id to specify the category for the Listing.

Taxonomy

Taxonomy has replaced Category in the Etsy API. You can send a taxonomy_id to createListing or updateListing. You must always use a seller taxonomy_id based on the getSellerTaxonomy, not a buyer taxonomy_id.

Marketplace Attributes

The fields who_made, when_made and is_supply are the so-called Marketplace Attributes that help buyers locate a Listing under the headings Handmade, Vintage and Supplies. When creating new Listings, these parameters are required. As of this writing, not all Listings on Etsy have their Marketplace Attributes set. These Listings will return null in these fields.

Private Listings (Experimental)

With the introduction of Custom Order Requests, sellers may now designate a listing as private, which indicates it is reserved for purchase by a single buyer. These listings have the attribute is_private.

Private listings have limited visibility on the site: they do not appear in search, browse or the seller's shop and are excluded from most Listing API endpoints. There is also a more restrictive set of actions that can be taken on private listings. Sellers cannot renew or feature these listings. Private listings also can't be added to Treasury Lists or Favorites.

Please see the note on findAllShopListingsActive for more information about interacting with private listings on behalf of a seller.

Fields

Field Visibility Level Permission Scope Type Description
listing_id public none int The listing's numeric ID.
state public none string One of active, removed, sold_out, expired, alchemy, edit, create, private, or unavailable.
user_id public none int The numeric ID of the user who posted the item.
category_id public none int Deprecated: The category parameter is no longer supported—you must pass a buyer taxonomy id instead.
title public none string The listing's title. This string is valid if it does not match the following pattern: /[^\p{L}\p{Nd}\p{P}\p{Sm}\p{Zs}™©®]/u. The characters %, :, & and + can only be used once each.
description public none string A description of the item.
creation_tsz public none float Creation time, in epoch seconds.
ending_tsz public none float The listing's expiration date and time, in epoch seconds.
original_creation_tsz public none float The date and time the listing was originally posted, in epoch seconds.
last_modified_tsz public none float The date and time the listing was updated, in epoch seconds.
price public none string The item's price (will be treated as private for sold listings).
Note: The price is the minimum possible price. The getInventory method will detail exact prices for available offerings.
currency_code public none string The ISO (alphabetic) code for the item's currency.
quantity public none int The quantity of this item available for sale.
Note: The quantity is the total number of available offerings. The getInventory method will detail quantities for individual offerings.
sku public none array(string) A list of distinct SKUs applied to a listing.
tags public none array(string) A list of tags for the item. A tag is valid if it does not match the pattern: /[^\p{L}\p{Nd}\p{Zs}\-'™©®]/u
taxonomy_id public none int The seller taxonomy id of the listing.
suggested_taxonomy_id public none int Etsy's suggestion for the seller taxonomy_id for this listing. Etsy makes this suggestion if the listing does not have a taxonomy_id chosen by the seller.
taxonomy_path public none array(string) The name of the taxonomy node of the item and the names of that node's parents
materials public none array(string) A list of materials used in the item. A material is valid if it does not match the pattern: /[^\p{L}\p{Nd}\p{Zs}]/u
shop_section_id public none int The numeric ID of the shop section for this listing, can be null
state_tsz public none float The time at which the listing last changed state.
url public none string The full URL to the listing's page on Etsy.
views public none int The number of times the listing has been viewed on Etsy.com (does not include API views).
num_favorers public none int The number of members who've marked this Listing as a favorite
shipping_template_id public none int The numeric ID of the shipping template associated with the listing.
shipping_profile_id public none int Deprecated: Do not use
processing_min public none int The minimum number of days for processing for this listing.
processing_max public none int The maximum number of days for processing for this listing.
who_made public none enum(i_did, collective, someone_else) Who made the item being listed.
is_supply public none boolean True if the listing is a supply.
when_made public none enum(made_to_order, 2020_2023, 2010_2019, 2004_2009, before_2004, 2000_2003, 1990s, 1980s, 1970s, 1960s, 1950s, 1940s, 1930s, 1920s, 1910s, 1900s, 1800s, 1700s, before_1700) When was the item made.
item_weight public none int How much the item weighs.
item_weight_unit public none enum(oz, lb, g, kg) The units used to represent the weight of this item.
item_length public none int How long the item is.
item_width public none int How wide the item is.
item_height public none int How tall the item is.
item_dimensions_unit public none enum(in, ft, mm, cm, m) The units used to represent the dimensions of this item.
is_private public none boolean Is this listing a private listing that is intendend for a specific buyer and hidden from shop view.
Note: This field is experimental and may change at any time.
style public none array(string) Style of this listing. Each style is a free-form text string such as "Formal", or "Steampunk". A Listing may have up to two styles. A style is valid if it does not match the pattern: /[^\p{L}\p{Nd}\p{Zs}]/u
non_taxable public none boolean If this flag is true, any applicable shop tax rates will not be applied to this listing on checkout.
is_customizable public none boolean If this flag is true, a buyer may contact the seller for a customized order. Can only be set when the shop accepts custom orders and defaults to true in that case.
is_digital public none boolean True if this listing is for a digital download.
file_data public none string Written description of the files attached to this digital listing.
can_write_inventory private listings_r boolean True if this listing can be updated with the new inventory endpoints
has_variations public none boolean True if variations are available for this Listing.
should_auto_renew public none boolean True if this listing has been set to automatic renewals.
language public none language The IETF language tag (e.g. 'fr') for the language in which the listing is returned.

Associations

Association Visibility Level Permission Scope Type Description
User public none User The user who posted the listing.
Shop public none Shop The shop to which the listing belongs.
Section public none ShopSection The shop section to which the listing belongs.
Images public none array(ListingImage) An array of images for the listing, can include up to 10 images.
MainImage public none ListingImage The main image associated with this Listing
ShippingInfo public none array(ShippingInfo) An array of destinations and shipping prices for this listing.
ShippingTemplate public none ShippingTemplate The linked shipping template
ShippingUpgrades public none array(ShippingUpgrade) An array of shipping upgrades for this listing.
PaymentInfo public none array(PaymentTemplate) An array of accepted payment methods for this listing.
Translations public none array(ListingTranslation) An array of translations for this Listing.
Attributes public none array(PropertyValue) An array of attributes for this Listing.
Inventory public none ListingInventory An array of inventory data for this Listing.
Note: This can only be used with the getListing, createListing, and updateListing methods.
Variations public none array(Variations_Property) An array of variations for this Listing.
Note: This can only be used with the getListing, createListing, updateListing, and getTransaction methods.
Deprecated: May return inaccurate data. Use the Inventory association instead.
VariationImage public none ListingVariationImage Associations of variations and images

Methods

createListing

Method Name createListing
Synopsis Creates a new Listing.
HTTP Method POST
URI /listings
Parameters
Name Required Default Type
quantity Y   int
title Y   string
description Y   text
price Y   float
materials N   array(string)
shipping_template_id N   int
taxonomy_id Y   int
shop_section_id N   int
image_ids N   array(int)
is_customizable N   boolean
non_taxable N   boolean
image N   image
state N active enum(active, draft)
processing_min N   int
processing_max N   int
tags N   array(string)
who_made Y   enum(i_did, collective, someone_else)
is_supply Y   boolean
when_made Y   enum(made_to_order, 2020_2023, 2010_2019, 2004_2009, before_2004, 2000_2003, 1990s, 1980s, 1970s, 1960s, 1950s, 1940s, 1930s, 1920s, 1910s, 1900s, 1800s, 1700s, before_1700)
style N   array(string)
Requires OAuth Y
Permission Scope listings_w
Notes
A shipping_template_id is required when creating a listing.
All listings created on Etsy must be actual items for sale. Please see our guidelines for testing with live listings.
Creating a listing creates a single inventory products with the supplied price and quantity. Use updateInventory to add more products.
The 'item_weight_unit' and 'item_dimensions_unit' fields will default to 'oz' and 'in' respectively when using calculated shipping. Be sure to provide actual values for these fields, or omit them entirely if they're not needed.

findAllFeaturedListings

Method Name findAllFeaturedListings
Synopsis Finds all FeaturedTreasury listings.
HTTP Method GET
URI /featured_treasuries/listings
Parameters
Name Required Default Type
limit N 25 int
offset N 0 int
page N   int
region N __ALL_REGIONS__ region
Requires OAuth N
Permission Scope none

getListing

Method Name getListing
Synopsis Retrieves a Listing by id.
HTTP Method GET
URI /listings/:listing_id
Parameters
Name Required Default Type
listing_id Y   array(int)
Requires OAuth N
Permission Scope none

updateListing

Method Name updateListing
Synopsis Updates a Listing
HTTP Method PUT
URI /listings/:listing_id
Parameters
Name Required Default Type
listing_id Y   int
quantity N   int
Deprecated: Quantities must be updated using updateInventory.
title N   string
description N   text
price N   float
Deprecated: Prices must be updated using updateInventory.
materials N   array(string)
renew N   boolean
shipping_template_id N   int
shop_section_id N   int
state N active enum(active, inactive, draft)
image_ids N   array(int)
is_customizable N   boolean
item_weight N   float
item_length N   float
item_width N   float
item_height N   float
item_weight_unit N   string
item_dimensions_unit N   string
non_taxable N   boolean
taxonomy_id N   int
tags N   array(string)
who_made N   enum(i_did, collective, someone_else)
is_supply N   boolean
when_made N   enum(made_to_order, 2020_2023, 2010_2019, 2004_2009, before_2004, 2000_2003, 1990s, 1980s, 1970s, 1960s, 1950s, 1940s, 1930s, 1920s, 1910s, 1900s, 1800s, 1700s, before_1700)
style N   array(string)
processing_min N   int
processing_max N   int
featured_rank N   featured_rank
Requires OAuth Y
Permission Scope listings_w
Notes
Due to description being optional for draft listings created on Etsy.com, you must ensure this field is set before activating a draft listing. You can also include the description parameter during activation to update the listing's description.

deleteListing

Method Name deleteListing
Synopsis Deletes a Listing
HTTP Method DELETE
URI /listings/:listing_id
Parameters
Name Required Default Type
listing_id Y   int
Requires OAuth Y
Permission Scope listings_d

findAllListingActive

Method Name findAllListingActive
Synopsis Finds all active Listings. (Note: the sort_on and sort_order options only work when combined with one of the search options: keywords, color, tags, location, etc.)
HTTP Method GET
URI /listings/active
Parameters
Name Required Default Type
limit N 25 int
offset N 0 int
page N   int
keywords N   text
sort_on N created enum(created, price, score)
sort_order N down enum(up, down)
min_price N   float
max_price N   float
color N   color_triplet
color_accuracy N 0 color_wiggle
tags N   array(string)
taxonomy_id N   int
location N   string
lat N   latitude
lon N   longitude
region N   region
geo_level N city enum(city, state, country)
accepts_gift_cards N false boolean
translate_keywords N false boolean
Requires OAuth N
Permission Scope none
Notes
The 'category' parameter is no longer supported. You must pass a Buyer Taxonomy id instead. Please see the documentation for the Taxonomy API

getInterestingListings

Method Name getInterestingListings
Synopsis Collects the list of interesting listings
HTTP Method GET
URI /listings/interesting
Parameters
Name Required Default Type
limit N 25 int
offset N 0 int
page N   int
Requires OAuth N
Permission Scope none

getTrendingListings

Method Name getTrendingListings
Synopsis Collects the list of listings used to generate the trending listing page
HTTP Method GET
URI /listings/trending
Parameters
Name Required Default Type
limit N 25 int
offset N 0 int
page N   int
Requires OAuth N
Permission Scope none

findAllListingsForFeaturedTreasuryId

Method Name findAllListingsForFeaturedTreasuryId
Synopsis Finds all listings for a certain FeaturedTreasury.
HTTP Method GET
URI /featured_treasuries/:featured_treasury_id/listings
Parameters
Name Required Default Type
featured_treasury_id Y   int
Requires OAuth N
Permission Scope none

findAllActiveListingsForFeaturedTreasuryId

Method Name findAllActiveListingsForFeaturedTreasuryId
Synopsis Finds all active listings for a certain FeaturedTreasury.
HTTP Method GET
URI /featured_treasuries/:featured_treasury_id/listings/active
Parameters
Name Required Default Type
featured_treasury_id Y   int
Requires OAuth N
Permission Scope none

findAllCurrentFeaturedListings

Method Name findAllCurrentFeaturedListings
Synopsis Finds FeaturedTreasury listings that are currently displayed on a regional homepage.
HTTP Method GET
URI /featured_treasuries/listings/homepage_current
Parameters
Name Required Default Type
region N US region
Requires OAuth N
Permission Scope none

findAllReceiptListings

Method Name findAllReceiptListings
Synopsis Finds all listings in a receipt
HTTP Method GET
URI /receipts/:receipt_id/listings
Parameters
Name Required Default Type
limit N 25 int
offset N 0 int
page N   int
receipt_id Y   int
Requires OAuth Y
Permission Scope transactions_r

findAllShopListingsActive

Method Name findAllShopListingsActive
Synopsis Finds all active Listings associated with a Shop.

(NOTE: If calling on behalf of a shop owner in the context of listing management, be sure to include the parameter include_private = true. This will return private listings that are not publicly visible in the shop, but which can be managed. This is an experimental feature and may change.)
HTTP Method GET
URI /shops/:shop_id/listings/active
Parameters
Name Required Default Type
limit N 25 int
offset N 0 int
page N   int
shop_id Y   shop_id_or_name
keywords N   string
sort_on N created enum(created, price, score)
sort_order N down enum(up, down)
min_price N   float
max_price N   float
color N   color_triplet
color_accuracy N 0 color_wiggle
tags N   array(string)
taxonomy_id N   int
translate_keywords N false boolean
include_private N 0 boolean
Requires OAuth N
Permission Scope none
Notes
The 'category' parameter is no longer supported. You must pass a Buyer Taxonomy id instead. Please see the documentation for the Taxonomy API

findAllShopListingsDraft

Method Name findAllShopListingsDraft
Synopsis Finds all of a Shop's draft listings
HTTP Method GET
URI /shops/:shop_id/listings/draft
Parameters
Name Required Default Type
shop_id Y   shop_id_or_name
limit N 25 int
offset N 0 int
page N   int
Requires OAuth Y
Permission Scope listings_r

findAllShopListingsExpired

Method Name findAllShopListingsExpired
Synopsis Retrieves Listings associated to a Shop that are expired
HTTP Method GET
URI /shops/:shop_id/listings/expired
Parameters
Name Required Default Type
shop_id Y   shop_id_or_name
limit N 25 int
offset N 0 int
page N   int
Requires OAuth Y
Permission Scope listings_r

getShopListingExpired

Method Name getShopListingExpired
Synopsis Retrieves a Listing associated to a Shop that is inactive
HTTP Method GET
URI /shops/:shop_id/listings/expired/:listing_id
Parameters
Name Required Default Type
shop_id Y   shop_id_or_name
listing_id Y   int
Requires OAuth Y
Permission Scope listings_r

findAllShopListingsFeatured

Method Name findAllShopListingsFeatured
Synopsis Retrieves Listings associated to a Shop that are featured
HTTP Method GET
URI /shops/:shop_id/listings/featured
Parameters
Name Required Default Type
shop_id Y   shop_id_or_name
limit N 25 int
offset N 0 int
page N   int
Requires OAuth N
Permission Scope none

findAllShopListingsInactive

Method Name findAllShopListingsInactive
Synopsis Retrieves Listings associated to a Shop that are inactive
HTTP Method GET
URI /shops/:shop_id/listings/inactive
Parameters
Name Required Default Type
shop_id Y   shop_id_or_name
limit N 25 int
offset N 0 int
page N   int
Requires OAuth Y
Permission Scope listings_r

getShopListingInactive

Method Name getShopListingInactive
Synopsis Retrieves a Listing associated to a Shop that is inactive
HTTP Method GET
URI /shops/:shop_id/listings/inactive/:listing_id
Parameters
Name Required Default Type
shop_id Y   shop_id_or_name
listing_id Y   int
Requires OAuth Y
Permission Scope listings_r

findAllShopSectionListings

Method Name findAllShopSectionListings
Synopsis Finds all listings within a shop section
HTTP Method GET
URI /shops/:shop_id/sections/:shop_section_id/listings
Parameters
Name Required Default Type
limit N 25 int
offset N 0 int
page N   int
shop_id Y   shop_id_or_name
shop_section_id Y   int
Requires OAuth N
Permission Scope none

findAllShopSectionListingsActive

Method Name findAllShopSectionListingsActive
Synopsis Finds all listings within a shop section
HTTP Method GET
URI /shops/:shop_id/sections/:shop_section_id/listings/active
Parameters
Name Required Default Type
limit N 25 int
offset N 0 int
page N   int
shop_id Y   shop_id_or_name
shop_section_id Y   array(int)
sort_on N created enum(created, price)
sort_order N down enum(up, down)
Requires OAuth N
Permission Scope none

findAllCartListings

Method Name findAllCartListings
Synopsis Finds all listings in a given Cart
HTTP Method GET
URI /users/:user_id/carts/:cart_id/listings
Parameters
Name Required Default Type
user_id Y   user_id_or_name
cart_id Y   cart_id
Requires OAuth Y
Permission Scope cart_rw

Open API v3New

Your developer account