Sdílet prostřednictvím


Etsy (Independent Publisher)

This connector uses your API key to access various Etsy.com features. It supports actions for inventory, sales orders, and shop management. All actions are based on Etsy Open API v3 which does have endpoints that are still in beta. If such as actions use the beta API, the action with include Beta in the title and will return a 501 response code.

This connector is available in the following products and regions:

Service Class Regions
Logic Apps Standard All Logic Apps regions except the following:
     -   Azure Government regions
     -   Azure China regions
     -   US Department of Defense (DoD)
Power Automate Premium All Power Automate regions except the following:
     -   US Government (GCC)
     -   US Government (GCC High)
     -   China Cloud operated by 21Vianet
     -   US Department of Defense (DoD)
Power Apps Premium All Power Apps regions except the following:
     -   US Government (GCC)
     -   US Government (GCC High)
     -   China Cloud operated by 21Vianet
     -   US Department of Defense (DoD)
Contact
Name Troy Taylor
URL https://www.hitachisolutions.com
Email ttaylor@hitachisolutions.com
Connector Metadata
Publisher Troy Taylor, Hitachi Solutions
Website https://www.etsy.com/
Privacy policy https://www.etsy.com/legal/privacy/
Categories Commerce

Creating a connection

The connector supports the following authentication types:

Default Parameters for creating connection. All regions Not shareable

Default

Applicable: All regions

Parameters for creating connection.

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Name Type Description Required
API key securestring The API key for this api True

Throttling Limits

Name Calls Renewal Period
API calls per connection 100 60 seconds

Actions

Create a draft listing

Creates a physical draft listing product in a shop on the Etsy channel.

Create a listing translation

Creates a listing translation by listing ID and language.

Create a Shipment Receipt

Submits tracking information for a shop receipt, which creates a shop receipt Shipment entry for the given receipt ID. Each time you successfully submit tracking info, Etsy sends a notification email to the buyer User. When send BCC is true, Etsy sends shipping notifications to the seller as well. When tracking code and carrier name aren't sent, the receipt is marked as shipped only.

Create a shipping profile

Creates a new shipping profile. You can pass a country ISO code or a region when creating a shipping profile, but not both. Only one is required. You must pass either a shipping carrier ID and mail class, or both min and max delivery days.

Create a shipping profile destination

Creates a new shipping destination, which sets the shipping cost, carrier, and class for a destination in a shipping profile. This assigns costs using the currency of the associated shop. Set the destination using either destination country ISO or destination region; destination country ISO and destination region are mutually exclusive — set one or the other. Setting both triggers error 400. If the request sets neither destination country ISO nor destination region, the default destination is everywhere. You must also either assign both a shipping carrier ID and mail class or both min delivery days and max delivery days.

Create a shipping profile upgrade

Creates a new shipping profile upgrade, which can establish a price for a shipping option, such as an alternate carrier or faster delivery.

Create a shop section

Creates a new section in a specific shop.

Delete a file from listing

When you delete the final file for a digital listing, the listing converts into a physical listing. The response to a delete request returns a list of the remaining file records associated with the given listing.

Delete a listing

This action deletes a shop listing. A listing can be deleted only if the state is one of the following: SOLD_OUT, DRAFT, EXPIRED, INACTIVE, ACTIVE and is_available or ACTIVE and has seller flags: SUPRESSED (frozen), VACATION, CUSTOM_SHOPS (pattern), SELL_ON_FACEBOOK

Delete a listing image

Deletes a listing image. A copy of the file remains on our servers, and so a deleted image may be re-associated with the listing without re-uploading the original image.

Delete a listing property

Deletes a property from a listing.

Delete a shipping profile

Deletes a shipping profile by given ID.

Delete a shipping profile destination

Deletes a shipping destination and removes the destination option from every listing that uses the associated shipping profile. A shipping profile requires at least one shipping destination, so this endpoint cannot delete the final shipping destination for any shipping profile. To delete the final shipping destination from a shipping profile, you must delete the entire shipping profile.

Delete a shipping profile upgrade

Deletes a shipping profile upgrade and removes the upgrade option from every listing that uses the associated shipping profile.

Get a file from a listing

Retrieves a single file associated with the given digital listing. Requesting a file from a physical listing returns an empty result.

Get a list of payments

Retrieves a list of payments from a shop identified by shop ID. You can also filter results using a list of payment IDs.

Get a listing

Retrieves a listing record by listing ID.

Get a listing's images

Retrieves all listing image resources for a listing with a specific listing ID.

Get a listing's inventory

Retrieves the inventory record for a listing. Listings you did not edit using the Etsy.com inventory tools have no inventory records. This endpoint returns SKU data if you are the owner of the inventory records being fetched.

Get a listing's offering

Get an offering for a listing.

Get a listing's product

Retrieve a listing product by ID.

Get a listing's properties

Returns a list of a listing's properties.

Get a listing's property (Beta)

Retrieves a listing's property. Development for this endpoint is in progress. It will only return a 501 response.

Get a listing's translation

Returns the translation for a listing in the given language.

Get a listing image

Retrieves the references and metadata for a listing image with a specific image ID.

Get a payment from a payment account ledger entry ID

Get a Payment from a Payment Account Ledger Entry ID, if applicable.

Get a payment from a specific receipt

Retrieves a payment from a specific receipt, identified by receipt ID, from a specific shop, identified by shop ID.

Get a receipt

Retrieves a receipt, identified by a receipt ID, from an Etsy shop.

Get a receipt's transaction

Retrieves the list of transactions associated with a specific receipt.

Get a shipping profile

Retrieves a shipping profile referenced by shipping profile ID.

Get a shop's transaction

Retrieves the list of transactions associated with a shop.

Get a shop payment account ledger's entries

Retrieve the entries of a shop's payment account ledger.

Get a transaction

Retrieves a transaction by transaction ID.

Get active listings

A list of all active listings on Etsy paginated by their creation date. Without sort order listings will be returned newest-first by default.

Get active listings by shop

Retrieves a list of all active listings on Etsy in a specific shop, paginated by listing creation date.

Get all listing files

Retrieves all the files associated with the given digital listing. Requesting files from a physical listing returns an empty result.

Get featured listings by shop

Retrieves listings associated to a shop that are featured.

Get listing's variation images

Gets all variation images on a listing.

Get listings by ID

Allows to query multiple listing IDs at once. Limit 100 IDs maximum per query.

Get listings by shop

Returns listings that belong to a Shop. Listings can be filtered using the state parameter.

Get listings by shop receipt

Gets all listings associated with a receipt.

Get listings by shop section ID

Retrieves all the listings from the section of a specific shop.

Get product properties by taxonomy ID

Retrieves a list of product properties, with applicable scales and values, supported for a specific seller taxonomy ID.

Get profile destinations by shipping profile

Retrieves a list of shipping destination objects associated with a shipping profile.

Get receipts

Requests the shop receipts from a specific shop, unfiltered or filtered by receipt ID range or offset, date, paid, and/or shipped purchases.

Get reviews

Retrieves the reviews from a shop given its ID.

Get seller taxonomy nodes

Retrieves the full hierarchy tree of seller taxonomy nodes.

Get shipping carriers

Retrieves a list of available shipping carriers and the mail classes associated with them for a given country.

Get shipping profile upgrades

Retrieves the list of shipping profile upgrades assigned to a specific shipping profile.

Get shipping profiles

Retrieves a list of shipping profiles available in the specific Etsy shop identified by its shop ID.

Get shop by owner ID

Retrieves the shop identified by the shop owner's user ID.

Get shop section

Retrieves a shop section, referenced by section ID and shop ID.

Get shop sections

Retrieves the list of shop sections in a specific shop identified by shop ID.

Get user

Returns user profile for the user identified by a user ID.

Get user's address

Retrieves the user's address. Development for this endpoint is in progress. It will only return a 501 response.

Get user addresses

Retrieve a list of user addresses.

Ping

Check to confirm connectivity to the Etsy API with an application.

Retrieve a listing's transactions

Retrieves the list of transactions associated with a listing.

Search shops

Returns a list of shops with the matching name.

Update a listing

Updates a listing, identified by a listing ID, for a specific shop identified by a shop ID.

Update a listing's inventory

Updates the inventory for a listing identified by a listing ID. The update fails if the supplied values for product SKU, offering quantity, and/or price are incompatible with values in on property fields. When setting a price, assign a float equal to amount divided by divisor as specified in the money resource.

Update a listing's variation images

Creates variation images on a listing.

Update a listing property

Updates or populates the properties list defining product offerings for a listing. Each offering requires both a value and a value ID that are valid for a scale ID assigned to the listing or that you assign to the listing with this request.

Update a listing translation

Updates a listing translation by listing ID and language.

Update a shipping profile

Changes the settings in a shipping profile.

Update a shipping profile destination

Updates an existing shipping destination, which can set or reassign the shipping cost, carrier, and class for a destination.

Update a shipping profile upgrade

Updates a shipping profile upgrade and updates any listings that use the shipping profile.

Update a shop

Update a shop. Assumes that all string parameters are provided in the shop's primary language.

Upload a listing file

Uploads a new file for a digital listing, or associates an existing file with a specific listing. You must either provide the listing file ID of an existing file, or the name and binary file data for a file to upload. Associating an existing file to a physical listing converts the physical listing into a digital listing, which removes all shipping costs and any product and inventory variations.

Upload a listing image

Uploads or assigns an image to a listing identified by a shop ID with a listing ID. To upload a new image, set the image file as the value for the image parameter. You can assign a previously deleted image to a listing using the deleted image's image ID in the listing image ID parameter. When a request contains both image and listing image ID parameter values, the endpoint uploads the image in the image parameter only.

Create a draft listing

Creates a physical draft listing product in a shop on the Etsy channel.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Quantity
quantity True integer

The positive non-zero number of products available for purchase in the listing.

Title
title True string

The listing's title string. Valid title strings contain only letters, numbers, punctuation marks, mathematical symbols, whitespace characters, ™, ©, and ®. (regex: /[^\p{L}\p{Nd}\p{P}\p{Sm}\p{Zs}™©®]/u) You can only use the %, :, & and + characters once each.

Description
description True string

A description string of the product for sale in the listing.

Price
price True float

The positive non-zero price of the product. (Sold product listings are private) Note: The price is the minimum possible price.

Who Made
who_made True string

An string inidcated who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

When Made
when_made string

A string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Taxonomy ID
taxonomy_id True integer

The numeric taxonomy ID of the listing. The seller manages listing taxonomy IDs for their shop.

Shipping Profile ID
shipping_profile_id True integer

The numeric ID of the shipping profile associated with the listing.

Materials
materials string

A array of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u)

Shop Section ID
shop_section_id integer

The numeric ID of the shop section for this listing.

Processing Minimum
processing_min integer

The minimum number of days required to process this listing.

Processing Maximum
processing_max integer

The maximum number of days required to process this listing.

Tags
tags string

An array of tag strings for the listing. Valid tag strings contain only letters, numbers, whitespace characters, -, ', ™, ©, and ®. (regex: /[^\p{L}\p{Nd}\p{Zs}-'™©®]/u)

Recipient
recipient string

A string indicating a person for whom this product would make an appropriate gift.

Occasion
occasion string

A string indicating an occassion for which this product would make an appropriate gift.

Styles
styles string

An array of style strings for this listing, each of which is free-form text string such as Formal, or Steampunk. A Listing may have up to two styles. Valid style strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u)

Item Weight
item_weight float

The numeric weight of the product measured in units set in item weight unit.

Item Length
item_length integer

The numeric length of the product measured in units set in item dimensions unit.

Item Width
item_width float

The numeric width of the product measured in units set in 'item dimensions unit'.

Item Height
item_height float

The numeric height of the product measured in units set in 'item dimensions unit'.

Item Weight Unit
item_weight_unit string

A string defining the units used to measure the weight of the product.

Item Dimensions Unit
item_dimensions_unit string

A string defining the units used to measure the dimensions of the product.

Is Personalizable
is_personalizable boolean

When true, this listing is personalizable.

Image IDs
image_ids string

An array of numeric image IDs of the images in a listing, which can include up to 10 images.

Is Supply
is_supply boolean

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who made' and 'when made'.

Is Customizable
is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

Is Taxable
is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

Returns

A listing from a shop, which contains a product quantity, title, description, price, etc.

ShopListing
ShopListing

Create a listing translation

Creates a listing translation by listing ID and language.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Language
language True string

The IETF language tag for the language of this translation. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

Title
title True string

The title of the Listing of this Translation.

Description
description True string

The description of the Listing of this Translation.

Tags
tags string

The tags of the Listing of this Translation.

Returns

Represents the translation data for a Listing.

ListingTranslation
ListingTranslation

Create a Shipment Receipt

Submits tracking information for a shop receipt, which creates a shop receipt Shipment entry for the given receipt ID. Each time you successfully submit tracking info, Etsy sends a notification email to the buyer User. When send BCC is true, Etsy sends shipping notifications to the seller as well. When tracking code and carrier name aren't sent, the receipt is marked as shipped only.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Receipt ID
receipt_id True integer

The receipt to submit tracking for.

Tracking Code
tracking_code string

The tracking code for this receipt.

Carrier Name
carrier_name string

The carrier name for this receipt.

Send BCC
send_bcc boolean

If true, the shipping notification will be sent to the seller as well

Returns

The record of a purchase from a shop. Shop receipts display monetary values using the shop's currency.

ShopReceipt
ShopReceipt

Create a shipping profile

Creates a new shipping profile. You can pass a country ISO code or a region when creating a shipping profile, but not both. Only one is required. You must pass either a shipping carrier ID and mail class, or both min and max delivery days.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Title
title True string

The name string of this shipping profile.

Origin Country ISO
origin_country_iso True string

The ISO code of the country from which the listing ships.

Primary Cost
primary_cost True float

The cost of shipping to this country/region alone, measured in the store's default currency.

Secondary Cost
secondary_cost True float

The cost of shipping to this country/region with another item, measured in the store's default currency.

Minimum Processing Time
min_processing_time True integer

The minimum time required to process to ship listings with this shipping profile.

Maximum Processing Time
max_processing_time True integer

The maximum processing time the listing needs to ship.

Processing Time Unit
processing_time_unit string

The unit used to represent how long a processing time is. A week is equivalent to 5 business days.

Destination Country ISO
destination_country_iso string

The ISO code of the country to which the listing ships. If null, request sets destination to destination region.

Destination Region
destination_region string

The code of the region to which the listing ships. A region represents a set of countries. Supported regions are Europe Union and Non-Europe Union (countries in Europe not in EU). If none, request sets destination to destination country ISO, or everywhere if destination country ISO is also null.

Origin Postal Code
origin_postal_code string

The postal code string (not necessarily a number) for the location from which the listing ships.

Shipping Carrier ID
shipping_carrier_id integer

The unique ID of a supported shipping carrier, which is used to calculate an estimated delivery date.

Mail Class
mail_class string

The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date.

Minimum Delivery Days
min_delivery_days integer

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped.

Maximum Delivery Days
max_delivery_days integer

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped.

Returns

Represents a profile used to set a listing's shipping information. Please note that it's not possible to create calculated shipping templates via the API. However, you can associate calculated shipping profiles created from Shop Manager with listings using the API.

ShopShippingProfile
ShopShippingProfile

Create a shipping profile destination

Creates a new shipping destination, which sets the shipping cost, carrier, and class for a destination in a shipping profile. This assigns costs using the currency of the associated shop. Set the destination using either destination country ISO or destination region; destination country ISO and destination region are mutually exclusive — set one or the other. Setting both triggers error 400. If the request sets neither destination country ISO nor destination region, the default destination is everywhere. You must also either assign both a shipping carrier ID and mail class or both min delivery days and max delivery days.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Shipping Profile ID
shipping_profile_id True integer

The numeric ID of the shipping profile associated with the listing.

Primary Cost
primary_cost True float

The cost of shipping to this country/region alone, measured in the store's default currency.

Secondary Cost
secondary_cost True string

The cost of shipping to this country/region with another item, measured in the store's default currency.

destination_country_iso
destination_country_iso string

destination_country_iso

destination_region
destination_region string

destination_region

shipping_carrier_id
shipping_carrier_id integer

shipping_carrier_id

mail_class
mail_class string

mail_class

min_delivery_days
min_delivery_days integer

min_delivery_days

max_delivery_days
max_delivery_days integer

max_delivery_days

Returns

Represents a shipping destination assigned to a shipping profile.

ShopShippingProfileDestination
ShopShippingProfileDestination

Create a shipping profile upgrade

Creates a new shipping profile upgrade, which can establish a price for a shipping option, such as an alternate carrier or faster delivery.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Shipping Profile ID
shipping_profile_id True integer

The numeric ID of the shipping profile associated with the listing.

Type
type True string

The type of the shipping upgrade. Domestic (0) or international (1).

Upgrade Name
upgrade_name True string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

Price
price True float

Additional cost of adding the shipping upgrade.

Secondary Price
secondary_price True float

Additional cost of adding the shipping upgrade for each additional item.

Shipping Carrier ID
shipping_carrier_id integer

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date.

Mail Class
mail_class string

The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date.

Minimum Delivery Days
min_delivery_days integer

min_delivery_days

Maximum Delivery Days
max_delivery_days integer

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped.

Returns

A representation of a shipping profile upgrade option.

ShopShippingProfileUpgrade
ShopShippingProfileUpgrade

Create a shop section

Creates a new section in a specific shop.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Title
title True string

The title string for a shop section.

Returns

A section within a shop, into which a user can sort listings.

ShopSection
ShopSection

Delete a file from listing

When you delete the final file for a digital listing, the listing converts into a physical listing. The response to a delete request returns a list of the remaining file records associated with the given listing.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Listing File ID
listing_file_id True integer

The unique numeric ID of a file associated with a digital listing.

Delete a listing

This action deletes a shop listing. A listing can be deleted only if the state is one of the following: SOLD_OUT, DRAFT, EXPIRED, INACTIVE, ACTIVE and is_available or ACTIVE and has seller flags: SUPRESSED (frozen), VACATION, CUSTOM_SHOPS (pattern), SELL_ON_FACEBOOK

Parameters

Name Key Required Type Description
Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Delete a listing image

Deletes a listing image. A copy of the file remains on our servers, and so a deleted image may be re-associated with the listing without re-uploading the original image.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Listing Image ID
listing_image_id True integer

The numeric ID of the primary listing image for this transaction.

Delete a listing property

Deletes a property from a listing.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Property ID
property_id True integer

The unique ID of an Etsy listing property.

Delete a shipping profile

Deletes a shipping profile by given ID.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Shipping Profile ID
shipping_profile_id True integer

The numeric ID of the shipping profile associated with the listing.

Returns

Represents a profile used to set a listing's shipping information. Please note that it's not possible to create calculated shipping templates via the API. However, you can associate calculated shipping profiles created from Shop Manager with listings using the API.

ShopShippingProfile
ShopShippingProfile

Delete a shipping profile destination

Deletes a shipping destination and removes the destination option from every listing that uses the associated shipping profile. A shipping profile requires at least one shipping destination, so this endpoint cannot delete the final shipping destination for any shipping profile. To delete the final shipping destination from a shipping profile, you must delete the entire shipping profile.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Shipping Profile ID
shipping_profile_id True integer

The numeric ID of the shipping profile associated with the listing.

Shipping Profile Destination ID
shipping_profile_destination_id True integer

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

Delete a shipping profile upgrade

Deletes a shipping profile upgrade and removes the upgrade option from every listing that uses the associated shipping profile.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Shipping Profile ID
shipping_profile_id True integer

The numeric ID of the shipping profile.

Upgrade ID
upgrade_id True integer

The numeric ID that is associated with a shipping upgrade

Get a file from a listing

Retrieves a single file associated with the given digital listing. Requesting a file from a physical listing returns an empty result.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Listing File ID
listing_file_id True integer

The unique numeric ID of a file associated with a digital listing.

Returns

A file associated with a digital listing.

ShopListingFile
ShopListingFile

Get a list of payments

Retrieves a list of payments from a shop identified by shop ID. You can also filter results using a list of payment IDs.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Payment ID
payment-ids True string

A comma-separated array of Payment IDs numbers.

Returns

Represents several payments made with Etsy Payments. All monetary amounts are in USD pennies unless otherwise specified.

Payments
Payments

Get a listing

Retrieves a listing record by listing ID.

Parameters

Name Key Required Type Description
Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Includes
includes string

An enumerated string that attaches a valid association. Acceptable inputs are 'shop', 'images' and 'user'.

Get a listing's images

Retrieves all listing image resources for a listing with a specific listing ID.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Returns

Represents a list of listing image resources, each of which contains the reference URLs and metadata for an image.

ListingImages
ListingImages

Get a listing's inventory

Retrieves the inventory record for a listing. Listings you did not edit using the Etsy.com inventory tools have no inventory records. This endpoint returns SKU data if you are the owner of the inventory records being fetched.

Parameters

Name Key Required Type Description
Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Includes
includes string

An enumerated string that attaches an valid association.

Returns

A representation of a single listing's inventory record with associations

ListingInventoryWithAssociations
ListingInventoryWithAssociations

Get a listing's offering

Get an offering for a listing.

Parameters

Name Key Required Type Description
Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Product ID
product_id True integer

The numeric ID for the product associated to this transaction.

Product Offering ID
product_offering_id True integer

The numeric ID for the product offering associated to this transaction.

Returns

A representation of an offering for a listing.

ListingInventoryProductOffering
ListingInventoryProductOffering

Get a listing's product

Retrieve a listing product by ID.

Parameters

Name Key Required Type Description
Listing ID
listing_id True integer

The listing to return a listing product for.

Product ID
product_id True integer

The numeric ID for a specific product purchased from a listing.

Returns

A representation of a product for a listing.

ListingInventoryProduct
ListingInventoryProduct

Get a listing's properties

Returns a list of a listing's properties.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Returns

Represents several listing property values.

ListingPropertyValues
ListingPropertyValues

Get a listing's property (Beta)

Retrieves a listing's property. Development for this endpoint is in progress. It will only return a 501 response.

Parameters

Name Key Required Type Description
Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Property ID
property_id True integer

The unique ID of an Etsy listing property.

Returns

A representation of structured data values.

ListingPropertyValue
ListingPropertyValue

Get a listing's translation

Returns the translation for a listing in the given language.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Language
language True string

The IETF language tag for the language of this translation. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

Returns

Represents the translation data for a Listing.

ListingTranslation
ListingTranslation

Get a listing image

Retrieves the references and metadata for a listing image with a specific image ID.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Listing Image ID
listing_image_id True integer

The numeric ID of the primary listing image for this transaction.

Returns

Reference urls and metadata for an image associated with a specific listing. The url_fullxfull parameter contains the URL for full-sized binary image file.

ListingImage
ListingImage

Get a payment from a payment account ledger entry ID

Get a Payment from a Payment Account Ledger Entry ID, if applicable.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Ledger Entry IDs
ledger_entry_ids True string

Array of integers.

Returns

Represents several payments made with Etsy Payments. All monetary amounts are in USD pennies unless otherwise specified.

Payments
Payments

Get a payment from a specific receipt

Retrieves a payment from a specific receipt, identified by receipt ID, from a specific shop, identified by shop ID.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Receipt ID
receipt_id True string

The numeric ID for the receipt associated to this transaction.

Returns

Represents several payments made with Etsy Payments. All monetary amounts are in USD pennies unless otherwise specified.

Payments
Payments

Get a receipt

Retrieves a receipt, identified by a receipt ID, from an Etsy shop.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Receipt ID
receipt_id True integer

The numeric ID for the receipt associated to this transaction.

Returns

The record of a purchase from a shop. Shop receipts display monetary values using the shop's currency.

ShopReceipt
ShopReceipt

Get a receipt's transaction

Retrieves the list of transactions associated with a specific receipt.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Receipt ID
receipt_id True integer

The numeric ID for the receipt associated to this transaction.

Returns

A set of shop receipt transaction resources

ShopReceiptTransactions
ShopReceiptTransactions

Get a shipping profile

Retrieves a shipping profile referenced by shipping profile ID.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Shipping Profile ID
shipping_profile_id True integer

The numeric ID of the shipping profile associated with the listing.

Get a shop's transaction

Retrieves the list of transactions associated with a shop.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Limit
limit integer

The maximum number of results to return.

Offset
offset integer

The number of records to skip before selecting the first result.

Returns

A set of shop receipt transaction resources

ShopReceiptTransactions
ShopReceiptTransactions

Get a shop payment account ledger's entries

Retrieve the entries of a shop's payment account ledger.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Minimum Created
min_created True integer

The earliest unix timestamp for when a record was created.

Maximum Created
max_created True integer

The latest unix timestamp for when a record was created.

Limit
limit integer

The maximum number of results to return.

Offset
offset integer

The number of records to skip before selecting the first result.

Returns

A set of payment account ledger entry resources

PaymentAccountLedgerEntries
PaymentAccountLedgerEntries

Get a transaction

Retrieves a transaction by transaction ID.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Transaction ID
transaction_id True integer

The unique numeric ID for a transaction.

Returns

A transaction object associated with a shop receipt. Etsy generates one transaction per listing purchased as recorded on the order receipt.

ShopReceiptTransaction
ShopReceiptTransaction

Get active listings

A list of all active listings on Etsy paginated by their creation date. Without sort order listings will be returned newest-first by default.

Parameters

Name Key Required Type Description
Limit
limit integer

The maximum number of results to return.

Offset
offset integer

The number of records to skip before selecting the first result.

Includes
keywords string

Search term or phrase that must appear in all results.

Sort On
sort_on string

The value to sort a search result of listings on. NOTE: sort on only works when combined with one of the search options (keywords, region, etc.).

Sort Order
sort_order string

The ascending(up) or descending(down) order to sort listings by. NOTE: sort_order only works when combined with one of the search options (keywords, region, etc.).

Minimum Price
min_price float

The minimum price of listings to be returned by a search result.

Maximum Price
max_price float

The maximum price of listings to be returned by a search result.

Taxonomy ID
taxonomy_id integer

The numeric taxonomy ID of the listing. The seller manages listing taxonomy IDs for their shop.

Shop Location
shop_location string

Filters by shop location. If location cannot be parsed, Etsy responds with an error.

Returns

A set of shop listing resources.

ShopListings
ShopListings

Get active listings by shop

Retrieves a list of all active listings on Etsy in a specific shop, paginated by listing creation date.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Limit
limit integer

The maximum number of results to return.

Offset
offset integer

The number of records to skip before selecting the first result.

Includes
keywords string

Search term or phrase that must appear in all results.

Returns

A set of shop listing resources.

ShopListings
ShopListings

Get all listing files

Retrieves all the files associated with the given digital listing. Requesting files from a physical listing returns an empty result.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The numeric ID for the listing associated to this transaction.

Listing ID
listing_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Returns

Represents several ShopListingFiles.

ShopListingFiles
ShopListingFiles

Retrieves listings associated to a shop that are featured.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Limit
limit integer

The maximum number of results to return.

Offset
offset integer

The number of records to skip before selecting the first result.

Returns

A set of shop listing resources.

ShopListings
ShopListings

Get listing's variation images

Gets all variation images on a listing.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Returns

Represents several listing variation images.

ListingVariationImages
ListingVariationImages

Get listings by ID

Allows to query multiple listing IDs at once. Limit 100 IDs maximum per query.

Parameters

Name Key Required Type Description
Listing IDs
listing_ids True string

The array of numeric IDs for the listings in a specific Etsy shop.

Includes
includes string

An enumerated string that attaches a valid association.

Returns

A set of shop listing resources with associations.

ShopListingsWithAssociations
ShopListingsWithAssociations

Get listings by shop

Returns listings that belong to a Shop. Listings can be filtered using the state parameter.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

State
State string

An enumerated string from any of: active or inactive.

Limit
limit integer

The maximum number of results to return.

Offset
offset integer

The number of records to skip before selecting the first result.

Sort On
Sort On string

The value to sort a search result of listings on.

Sort Order
Sort Order string

The ascending(up) or descending(down) order to sort listings by.

Returns

A set of shop listing resources.

ShopListings
ShopListings

Get listings by shop receipt

Gets all listings associated with a receipt.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The numeric ID for the receipt associated to this transaction.

Receipt ID
receipt_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Limit
limit integer

The maximum number of results to return.

Offset
offset integer

The number of records to skip before selecting the first result.

Returns

A set of shop listing resources.

ShopListings
ShopListings

Get listings by shop section ID

Retrieves all the listings from the section of a specific shop.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Shop Section IDs
shop_section_ids True string

A array of numeric IDs for all sections in a specific Etsy shop.

Limit
limit integer

The maximum number of results to return.

Offset
offset integer

The number of records to skip before selecting the first result.

Sort On
sort_on string

The value to sort a search result of listings on.

Sort Order
sort_order string

The ascending(up) or descending(down) order to sort listings by.

Returns

A set of shop listing resources.

ShopListings
ShopListings

Get product properties by taxonomy ID

Retrieves a list of product properties, with applicable scales and values, supported for a specific seller taxonomy ID.

Parameters

Name Key Required Type Description
Taxonomy ID
taxonomy_id True string

The unique numeric ID of an Etsy taxonomy node, which is a metadata category for listings organized into the seller taxonomy hierarchy tree.

Returns

A list of product property definitions.

TaxonomyNodeProperties
TaxonomyNodeProperties

Get profile destinations by shipping profile

Retrieves a list of shipping destination objects associated with a shipping profile.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Shipping Profile ID
shipping_profile_id True integer

The numeric ID of the shipping profile associated with the listing.

Limit
limit integer

The maximum number of results to return.

Offset
offset integer

The number of records to skip before selecting the first result.

Returns

Represents a list of shipping destination objects.

ShopShippingProfileDestinations
ShopShippingProfileDestinations

Get receipts

Requests the shop receipts from a specific shop, unfiltered or filtered by receipt ID range or offset, date, paid, and/or shipped purchases.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Minimum Created
min_created integer

The earliest unix timestamp for when a record was created.

Maximum Created
max_created integer

The latest unix timestamp for when a record was created.

Earliest Last Modified
min_last_modified integer

The earliest unix timestamp for when a record last changed.

Latest Last Modified
max_last_modified integer

The latest unix timestamp for when a record last changed.

Limit
limit integer

The maximum number of results to return.

Offset
offset integer

The number of records to skip before selecting the first result.

Was Paid
was_paid boolean

When true, the seller received payment for the product(s) in this receipt.

Was Shipped
was_shipped boolean

When true, the seller shipped the product(s) in this receipt.

Returns

The receipts for a specific Shop.

ShopReceipts
ShopReceipts

Get reviews

Retrieves the reviews from a shop given its ID.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Limit
limit integer

The maximum number of results to return.

Offset
offset integer

The number of records to skip before selecting the first result.

Returns

A set of transaction review records left by Users.

TransactionReviews
TransactionReviews

Get seller taxonomy nodes

Retrieves the full hierarchy tree of seller taxonomy nodes.

Returns

A list of taxonomy nodes from the seller taxonomy tree.

SellerTaxonomyNodes
SellerTaxonomyNodes

Get shipping carriers

Retrieves a list of available shipping carriers and the mail classes associated with them for a given country.

Parameters

Name Key Required Type Description
Origin Country ISO
origin_country_iso True string

The ISO code of the country from which the listing ships.

Returns

Represents several ShippingCarriers.

ShippingCarriers
ShippingCarriers

Get shipping profile upgrades

Retrieves the list of shipping profile upgrades assigned to a specific shipping profile.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Shipping Profile ID
shipping_profile_id True integer

The numeric ID of the shipping profile associated with the listing.

Returns

A list of shipping upgrade options.

ShopShippingProfileUpgrades
ShopShippingProfileUpgrades

Get shipping profiles

Retrieves a list of shipping profiles available in the specific Etsy shop identified by its shop ID.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Returns

Represents a profile used to set a listing's shipping information. Please note that it's not possible to create calculated shipping templates via the API. However, you can associate calculated shipping profiles created from Shop Manager with listings using the API.

ShopShippingProfile
ShopShippingProfile

Get shop by owner ID

Retrieves the shop identified by the shop owner's user ID.

Parameters

Name Key Required Type Description
User ID
user_id True string

The numeric user ID of the user who owns this shop.

Returns

A shop created by an Etsy user.

Shop
Shop

Get shop section

Retrieves a shop section, referenced by section ID and shop ID.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Shop Section ID
shop_section_id True integer

The numeric ID of a section in a specific Etsy shop.

Returns

A section within a shop, into which a user can sort listings.

ShopSection
ShopSection

Get shop sections

Retrieves the list of shop sections in a specific shop identified by shop ID.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Returns

All the sections in a sprecific Shop.

ShopSections
ShopSections

Get user

Returns user profile for the user identified by a user ID.

Parameters

Name Key Required Type Description
User ID
user_id True integer

The unique positive non-zero numeric ID for an user.

Returns

Represents a single user of the site

User
User

Get user's address

Retrieves the user's address. Development for this endpoint is in progress. It will only return a 501 response.

Parameters

Name Key Required Type Description
User Address ID
user_address_id True integer

The numeric ID of the user's address.

Returns

Represents a user's address.

UserAddress
UserAddress

Get user addresses

Retrieve a list of user addresses.

Parameters

Name Key Required Type Description
Limit
limit integer

The maximum number of results to return.

Offset
offset integer

The number of records to skip before selecting the first result.

Returns

Represents several UserAddress records.

UserAddresses
UserAddresses

Ping

Check to confirm connectivity to the Etsy API with an application.

Returns

A confirmation that the current application has access to the Open API

Pong
Pong

Retrieve a listing's transactions

Retrieves the list of transactions associated with a listing.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Limit
limit integer

The maximum number of results to return.

Offset
offset integer

The number of records to skip before selecting the first result.

Returns

A set of shop receipt transaction resources

ShopReceiptTransactions
ShopReceiptTransactions

Search shops

Returns a list of shops with the matching name.

Parameters

Name Key Required Type Description
Shop Name
shop_name True string

The shop's name string.

Limit
limit integer

The maximum number of results to return.

Offset
offset integer

The number of records to skip before selecting the first result.

Returns

A set of Shop records.

Shops
Shops

Update a listing

Updates a listing, identified by a listing ID, for a specific shop identified by a shop ID.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Quantity
quantity integer

The positive non-zero number of products available for purchase in the listing.

Title
title string

The listing's title string. Valid title strings contain only letters, numbers, punctuation marks, mathematical symbols, whitespace characters, ™, ©, and ®. (regex: /[^\p{L}\p{Nd}\p{P}\p{Sm}\p{Zs}™©®]/u) You can only use the %, :, & and + characters once each.

Description
description string

A description string of the product for sale in the listing.

Price
price float

The positive non-zero price of the product. (Sold product listings are private) Note: The price is the minimum possible price.

Who Made
who_made string

An string inidcated who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

When Made
when_made string

A string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Taxonomy ID
taxonomy_id integer

The numeric taxonomy ID of the listing. The seller manages listing taxonomy IDs for their shop.

Shipping Profile ID
shipping_profile_id integer

The numeric ID of the shipping profile associated with the listing.

Materials
materials string

A array of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u)

Shop Section ID
shop_section_id integer

The numeric ID of the shop section for this listing.

Processing Minimum
processing_min integer

The minimum number of days required to process this listing.

Processing Maximum
processing_max integer

The maximum number of days required to process this listing.

Tags
tags string

An array of tag strings for the listing. Valid tag strings contain only letters, numbers, whitespace characters, -, ', ™, ©, and ®. (regex: /[^\p{L}\p{Nd}\p{Zs}-'™©®]/u)

Recipient
recipient string

A string indicating a person for whom this product would make an appropriate gift.

Occasion
occasion string

A string indicating an occassion for which this product would make an appropriate gift.

Styles
styles string

An array of style strings for this listing, each of which is free-form text string such as Formal, or Steampunk. A Listing may have up to two styles. Valid style strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u)

Item Weight
item_weight float

The numeric weight of the product measured in units set in item weight unit.

Item Length
item_length integer

The numeric length of the product measured in units set in item dimensions unit.

Item Width
item_width float

The numeric width of the product measured in units set in 'item dimensions unit'.

Item Height
item_height float

The numeric height of the product measured in units set in 'item dimensions unit'.

Item Weight Unit
item_weight_unit string

A string defining the units used to measure the weight of the product.

Item Dimensions Unit
item_dimensions_unit string

A string defining the units used to measure the dimensions of the product.

Is Personalizable
is_personalizable boolean

When true, this listing is personalizable.

Image IDs
image_ids string

An array of numeric image IDs of the images in a listing, which can include up to 10 images.

Is Supply
is_supply boolean

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who made' and 'when made'.

Is Customizable
is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

Is Taxable
is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

Featured Rank
featured_ rank integer

The positive non-zero numeric position in the featured listings of the shop with rank 1 listings appearing in the left-most position in featured listing on a shop’s home page.

Should Auto Renew
should_auto_renew boolean

When true, renews a listing for four months upon expriation. If set to true when previously false, etsy.com renews the listing before it expires, but the renewal period starts immidiately rather than extending the listing's expiration date. Any unused time remaining on the listing is lost. Renewals result in charges to a user's bill.

Type
type string

Indicates whether the listing is physical or a digital download.

Channels
channels string

An array of enumerated channel ID strings. A channel is a venue for sellers to reach buyers in order to make sales.

Returns

A listing from a shop, which contains a product quantity, title, description, price, etc.

ShopListing
ShopListing

Update a listing's inventory

Updates the inventory for a listing identified by a listing ID. The update fails if the supplied values for product SKU, offering quantity, and/or price are incompatible with values in on property fields. When setting a price, assign a float equal to amount divided by divisor as specified in the money resource.

Parameters

Name Key Required Type Description
Listing ID
listing_id True string

The numeric ID for the listing associated to this transaction.

Products
products True string

A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.

Price on Property
price_on_property string

An array of unique listing property ID integers for the properties that change product prices, if any. For example, if you charge specific prices for different sized products in the same listing, then this array contains the property ID for size.

Quantity on Property
quantity_on_property string

An array of unique listing property ID integers for the properties that change the quantity of the products, if any. For example, if you stock specific quantities of different colored products in the same listing, then this array contains the property ID for color.

SKU on Property
sku_on_property string

An array of unique listing property ID integers for the properties that change the product SKU, if any. For example, if you use specific skus for different colored products in the same listing, then this array contains the property ID for color.

Returns

A representation of a single listing's inventory record.

ListingInventory
ListingInventory

Update a listing's variation images

Creates variation images on a listing.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Variation Images
variation_images True string

A array of variation image data.

Returns

Represents several listing variation images.

ListingVariationImages
ListingVariationImages

Update a listing property

Updates or populates the properties list defining product offerings for a listing. Each offering requires both a value and a value ID that are valid for a scale ID assigned to the listing or that you assign to the listing with this request.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Property ID
property_id True integer

The unique ID of an Etsy listing property.

Value IDs
value_ids True integer

The numeric ID of a single Etsy.com measurement scale.

Values
values True string

An array of value strings for multiple Etsy listing property values.

Scale ID
scale_id integer

The numeric ID of a single Etsy.com measurement scale.

Returns

A representation of structured data values.

ListingPropertyValue
ListingPropertyValue

Update a listing translation

Updates a listing translation by listing ID and language.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Language
language True string

The IETF language tag for the language of this translation. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

Title
title True string

The title of the Listing of this Translation.

Description
description True string

The description of the Listing of this Translation.

Tags
tags string

The tags of the Listing of this Translation.

Returns

Represents the translation data for a Listing.

ListingTranslation
ListingTranslation

Update a shipping profile

Changes the settings in a shipping profile.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Shipping Profile ID
shipping_profile_id True integer

The numeric ID of the shipping profile associated with the listing.

Title
title string

The name string of this shipping profile.

Origin Country ISO
origin_country_iso string

The ISO code of the country from which the listing ships.

Minimum Processing Time
min_processing_time integer

The minimum time required to process to ship listings with this shipping profile.

Maximum Processing Time
max_processing_time integer

The maximum processing time the listing needs to ship.

Processing Time Unit
processing_time_unit string

The unit used to represent how long a processing time is. A week is equivalent to 5 business days. If none is provided, the unit is set to business_days.

Origin Postal Code
origin_postal_code string

The postal code string (not necessarily a number) for the location from which the listing ships.

Returns

Represents a profile used to set a listing's shipping information. Please note that it's not possible to create calculated shipping templates via the API. However, you can associate calculated shipping profiles created from Shop Manager with listings using the API.

ShopShippingProfile
ShopShippingProfile

Update a shipping profile destination

Updates an existing shipping destination, which can set or reassign the shipping cost, carrier, and class for a destination.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Shipping Profile ID
shipping_profile_id True string

The numeric ID of the shipping profile associated with the listing.

Shipping Profile Destination ID
shipping_profile_destination_id True string

The numeric ID of the shipping profile destinationassociated with the listing.

primary_cost
primary_cost string

primary_cost

secondary_cost
secondary_cost string

secondary_cost

destination_country_iso
destination_country_iso string

destination_country_iso

destination_region
destination_region string

destination_region

shipping_carrier_id
shipping_carrier_id integer

shipping_carrier_id

mail_class
mail_class string

mail_class

min_delivery_days
min_delivery_days integer

min_delivery_days

max_delivery_days
max_delivery_days integer

max_delivery_days

Returns

Represents a shipping destination assigned to a shipping profile.

ShopShippingProfileDestination
ShopShippingProfileDestination

Update a shipping profile upgrade

Updates a shipping profile upgrade and updates any listings that use the shipping profile.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Shipping Profile ID
shipping_profile_id True integer

The numeric ID of the shipping profile associated with the listing.

Upgrade ID
upgrade_id True integer

The numeric ID that is associated with a shipping upgrade

Type
type string

The type of the shipping upgrade. Domestic (0) or international (1).

Upgrade Name
upgrade_name string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

Price
price float

Additional cost of adding the shipping upgrade.

Secondary Price
secondary_price float

Additional cost of adding the shipping upgrade for each additional item.

Shipping Carrier ID
shipping_carrier_id integer

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date.

Mail Class
mail_class string

The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date.

Minimum Delivery Days
min_delivery_days integer

min_delivery_days

Maximum Delivery Days
max_delivery_days integer

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped.

Returns

A representation of a shipping profile upgrade option.

ShopShippingProfileUpgrade
ShopShippingProfileUpgrade

Update a shop

Update a shop. Assumes that all string parameters are provided in the shop's primary language.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Title
title string

A brief heading string for the shop's main page.

Announcement
announcement string

An announcement string to buyers that displays on the shop's homepage.

Sale Message
sale_message string

A message string sent to users who complete a purchase from this shop.

Digital Sale Message
digital_sale_message string

A message string sent to users who purchase a digital item from this shop.

Returns

A shop created by an Etsy user.

Shop
Shop

Upload a listing file

Uploads a new file for a digital listing, or associates an existing file with a specific listing. You must either provide the listing file ID of an existing file, or the name and binary file data for a file to upload. Associating an existing file to a physical listing converts the physical listing into a digital listing, which removes all shipping costs and any product and inventory variations.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Listing File ID
listing_file_id integer

The unique numeric ID of a file associated with a digital listing.

File
file True string

A binary file to upload.

Name
name string

The file name string of a file to upload

Rank
rank integer

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

Returns

A file associated with a digital listing.

ShopListingFile
ShopListingFile

Upload a listing image

Uploads or assigns an image to a listing identified by a shop ID with a listing ID. To upload a new image, set the image file as the value for the image parameter. You can assign a previously deleted image to a listing using the deleted image's image ID in the listing image ID parameter. When a request contains both image and listing image ID parameter values, the endpoint uploads the image in the image parameter only.

Parameters

Name Key Required Type Description
Shop ID
shop_id True integer

The unique positive non-zero numeric ID for an Etsy Shop.

Listing ID
listing_id True integer

The numeric ID for the listing associated to this transaction.

Image
image string

The file name string of a file to upload.

Listing Image ID
listing_image_id integer

The numeric ID of the primary listing image for this transaction.

Rank
rank integer

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

Overwrite
overwrite boolean

When true, this request replaces the existing image at a given rank.

Is Watermarked
is_watermarked boolean

When true, indicates that the uploaded image has a watermark.

Returns

Reference urls and metadata for an image associated with a specific listing. The url_fullxfull parameter contains the URL for full-sized binary image file.

ListingImage
ListingImage

Definitions

ShopListing

A listing from a shop, which contains a product quantity, title, description, price, etc.

Name Path Type Description
Listing ID
listing_id integer

The numeric ID for the listing associated to this transaction.

User ID
user_id integer

The numeric ID for the user posting the listing.

Shop ID
shop_id integer

The unique positive non-zero numeric ID for an Etsy Shop.

Title
title string

The listing's title string. Valid title strings contain only letters, numbers, punctuation marks, mathematical symbols, whitespace characters, ™, ©, and ®. (regex: /[^\p{L}\p{Nd}\p{P}\p{Sm}\p{Zs}™©®]/u) You can only use the %, :, & and + characters once each.

Description
description string

A description string of the product for sale in the listing.

State
state State

An enumerated string from any of: active or inactive. Note: Setting a draft listing to active will also publish the listing on etsy.com.

Creation Timestamp
creation_timestamp integer

The listing's creation time, in epoch seconds.

Ending Timestamp
ending_timestamp integer

The listing's expiration time, in epoch seconds.

Original Creation Timestamp
original_creation_timestamp integer

The listing's creation time, in epoch seconds.

Last Modified Timestamp
last_modified_timestamp integer

The time of the last update to the listing, in epoch seconds.

Last State Change Timestamp
state_timestamp integer

The date and time of the last state change of this listing.

Quantity
quantity integer

The positive non-zero number of products available for purchase in the listing. Note: The listing quantity is the sum of available offering quantities. You can request the quantities for individual offerings from the ListingInventory resource using the get listing inventory endpoint.

Shop Section ID
shop_section_id integer

The numeric ID of a section in a specific Etsy shop.

Featured Rank
featured_rank integer

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop’s home page.

URL
url string

The full URL to the listing's page on Etsy.

Number of Favorers
num_favorers integer

The number of users who marked this listing a favorite.

Non-taxable
non_taxable boolean

When true, applicable shop tax rates do not apply to this listing at checkout.

Is Customizable
is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

Is Peronalizable
is_personalizable boolean

When true, this listing is personalizable. The default value is null.

Personalization is Required
personalization_is_required boolean

When true, this listing requires personalization. The default value is null.

Maximum Personalization Character Count
personalization_char_count_max integer

This an integer value representing the maximum length for the personalization message entered by the buyer.

Personalization Instructions
personalization_instructions string

When true, this listing requires personalization. The default value is null.

Listing Type
listing_type boolean

An enumerated type string that indicates whether the listing is physical or a digital download.

Tags
tags array of string

A list of tag strings for the listing. Valid tag strings contain only letters, numbers, whitespace characters, -, ', ™, ©, and ®. (regex: /[^\p{L}\p{Nd}\p{Zs}\-'™©®]/u) Default value is null.

Materials
materials array of string

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

Shipping Profile ID
shipping_profile_id integer

The numeric ID of the shipping profile associated with the listing.

Minimum Processing Days
processing_min integer

The minimum number of days required to process this listing. Default value is null.

Maximum Processing Days
processing_max integer

The maximum number of days required to process this listing. Default value is null.

WhoMade
who_made WhoMade

An enumerated string inidcated who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

WhenMade
when_made WhenMade

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Supply Product
is_supply boolean

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

Item Weight
item_weight double

The numeric weight of the product measured in units set in item weight unit. Default value is null. If set, the value must be greater than 0.

ItemWeightUnit
item_weight_unit ItemWeightUnit

A string defining the units used to measure the weight of the product. Default value is null.

Item Length
item_length double

The numeric length of the product measured in units set in item dimensions unit. Default value is null. If set, the value must be greater than 0.

Item Width
item_width double

The numeric width of the product measured in units set in item dimensions unit. Default value is null. If set, the value must be greater than 0.

Item Height
item_height double

The numeric length of the product measured in units set in item dimensions unit. Default value is null. If set, the value must be greater than 0.

ItemDimensionsUnit
item_dimensions_unit ItemDimensionsUnit

A string defining the units used to measure the dimensions of the product. Default value is null.

Is Private
is_private boolean

When true, this is a private listing intendend for a specific buyer and hidden from shop view.

Recipient
recipient Recipient

An enumerated string indicating a person for whom this product would make an appropriate gift. Default value is null.

Occasion
occasion Occasion

An enumerated string indicating an occassion for which this product would make an appropriate gift. Default value is null.

Style
style array of string

An array of style strings for this listing, each of which is free-form text string such as Formal, or Steampunk. A Listing may have up to two styles. Valid style strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

File Data
file_data string

A string describing the files attached to a digital listing.

Has Variations
has_variations boolean

When true, the listing has variations.

Should Auto Renew
should_auto_renew boolean

When true, renews a listing for four months upon expriation. If set to true when previously false, etsy.com renews the listing before it expires, but the renewal period starts immidiately rather than extending the listing's expiration date. Any unused time remaining on the listing is lost. Renewals result in charges to a user's bill.

Language
language string

The IETF language tag for the default language of the listing. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

Money
price Money

A representation of an amount of money.

Taxonomy ID
taxonomy_id integer

The numeric taxonomy ID of the listing. The seller manages listing taxonomy IDs for their shop. See seller taxonomy for more information.

Money

A representation of an amount of money.

Name Path Type Description
Amount
amount integer

The amount of represented by this data.

Divisor
divisor integer

The divisor to render the amount.

Currency Code
currency_code string

The ISO currency code for this data.

ShopListingFile

A file associated with a digital listing.

Name Path Type Description
Listing File ID
listing_file_id integer

The unique numeric ID of a file associated with a digital listing.

Listing ID
listing_id integer

The numeric ID for the listing associated to this transaction.

Rank
rank integer

The numeric index of the display order position of this file in the listing, starting at 1.

Filename
filename string

The file name string for a file associated with a digital listing.

Filesize
filesize string

A human-readable format size string for the size of a file.

Size in Bytes
size_bytes integer

A number indicating the size of a file, measured in bytes.

Filetype
filetype string

A type string indicating a file's MIME type.

Create Timestamp
create_timestamp integer

The unique numeric timestamp of a file associated with a digital listing.

ShopListingFiles

Represents several ShopListingFiles.

Name Path Type Description
Count
count integer

The number of ShopListingFiles being returned..

Results
results array of ShopListingFile

An array of ShopListingFile resources.

ShopListings

A set of shop listing resources.

Name Path Type Description
Count
count integer

The number of shop listing resources found.

Results
results array of ShopListing

The shop listing resources found.

User

Represents a single user of the site

Name Path Type Description
User ID
user_id integer

The numeric ID of a user. This number is also a valid shop ID for the user's shop.

Login Name
login_name string

The user's login name string.

Primary Email
primary_email string

An email address string for the user's primary email address.

First Name
first_name string

The user's first name.

Last Name
last_name string

The user's last name.

Created Timestamp
create_timestamp integer

The date and time the user created their account, in epoch seconds.

Referred by User ID
referred_by_user_id integer

The numeric ID of the user who referred this user.

Use New Inventory Endpoints
use_new_inventory_endpoints boolean

Deprecated. Always true.

Is Seller
is_seller boolean

True if the user is seller.

Biography
bio string

The user's biography.

Gender
gender string

The user's gender.

Birth Month
birth_month string

The user's month of birth.

Birthday
birth_day string

The user's day of birth.

Buy Transaction Count
transaction_buy_count integer

The number of transactions where the user has bought.

Sold Transaction Count
transaction_sold_count integer

The number of transactions where the user has sold.

Shop

A shop created by an Etsy user.

Name Path Type Description
Shop ID
shop_id integer

The unique positive non-zero numeric ID for an Etsy Shop.

User ID
user_id integer

The numeric user ID of the user who owns this shop.

Shop Name
shop_name string

The shop's name string.

Created Date
create_date integer

The date and time this shop was created, in epoch seconds.

Title
title string

A brief heading string for the shop's main page.

Announcement
announcement string

An announcement string to buyers that displays on the shop's homepage.

Currency Code
currency_code string

The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.

Is On Vacation
is_vacation boolean

When true, this shop is not accepting purchases.

Vacation Message
vacation_message string

The shop's message string displayed when is_vacation is true.

Sale Message
sale_message string

A message string sent to users who complete a purchase from this shop.

Digital Sale Message
digital_sale_message string

A message string sent to users who purchase a digital item from this shop.

Updated Date
update_date integer

The date and time of the last update to the shop, in epoch seconds.

Active Listing Count
listing_active_count integer

The number of active listings in the shop.

Digital Listing Count
digital_listing_count integer

The number of digital listings in the shop.

Login Name
login_name string

The shop owner's login name string.

Accepts Custom Requests
accepts_custom_requests boolean

When true, the shop accepts customization requests.

Welcome Policy
policy_welcome string

The shop's policy welcome string (may be blank).

Payment Policy
policy_payment string

The shop's payment policy string (may be blank).

Shipping Policy
policy_shipping string

The shop's shipping policy string (may be blank).

Refund Policy
policy_refunds string

The shop's refund policy string (may be blank).

Additional Policies
policy_additional string

The shop's additional policies string (may be blank).

Seller Information
policy_seller_info string

The shop's seller infomation string (may be blank).

Policy Updated Date
policy_update_date integer

The date and time of the last update to the shop's policies, in epoch seconds.

Has Private Receipt Policy
policy_has_private_receipt_info boolean

When true, EU receipts display private info.

Has Unstructured Policies
has_unstructured_policies boolean

When true, the shop displays additional unstructured policy fields.

Privacy Policy
policy_privacy string

The shop's privacy policy string (may be blank).

Vacation Autoreply
vacation_autoreply string

The shop's automatic reply string displayed in new conversations when is_vacation is true.

URL
url string

The URL string for this shop.

Banner Image URL
image_url_760x100 string

The URL string for this shop's banner image.

Number of Favorers
num_favorers integer

The number of users who marked this shop a favorite.

Languages
languages array of string

A list of language strings for the shop's enrolled languages.

Icon Image URL
icon_url_fullxfull string

The URL string for this shop's icon image.

Is Using Structured Policies
is_using_structured_policies boolean

When true, the shop accepted using structured policies.

Has Onboarded Structured Policies
has_onboarded_structured_policies boolean

When true, the shop accepted OR declined after viewing structured policies onboarding.

Include Dispute Form Link
include_dispute_form_link boolean

When true, this shop's policies include a link to an EU online dispute form.

Is Direct Checkout Onboarded
is_direct_checkout_onboarded boolean

When true, the shop has onboarded onto Etsy Payments.

Is Calculated Shipping Eligible
is_calculated_eligible boolean

When true, the shop is elegible for calculated shipping profiles. (Only available in the US and Canada)

Is Opted In to Buyer Promise
is_opted_in_to_buyer_promise boolean

When true, the shop opted in to buyer promise.

Is US based
is_shop_us_based boolean

When true, the shop is based in the US.

Sales Transaction Count
transaction_sold_count integer

The total number of sales transactions for this shop

Shipping from Country ISO
shipping_from_country_iso string

The country iso the shop is shipping from.

Shop Location ISO
shop_location_country_iso string

The country iso where the shop is located.

Review Count
review_count integer

Number of reviews of shop listings in the past year.

Review Average
review_average double

Average rating based on reviews of shop listings in the past year.

ListingImage

Reference urls and metadata for an image associated with a specific listing. The url_fullxfull parameter contains the URL for full-sized binary image file.

Name Path Type Description
Listing ID
listing_id integer

The numeric ID for the listing associated to this transaction.

Listing Image ID
listing_image_id integer

The numeric ID of the primary listing image for this transaction.

Hex Code
hex_code string

The webhex string for the image's average color, in webhex notation.

Red Value
red integer

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

Green Value
green integer

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

Blue Value
blue integer

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

Hue Value
hue integer

The numeric hue equal to the image's average hue, from 0-360 (HSV color).

Saturation Value
saturation integer

The numeric saturation equal to the image's average saturation, from 0-100 (HSV color).

Brightness Value
brightness integer

The numeric brightness equal to the image's average brightness, from 0-100 (HSV color).

Is Black and White
is_black_and_white boolean

When true, the image is in black & white.

Creation Time
creation_tsz integer

The listing image's creation time, in epoch seconds.

Rank
rank integer

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

75x75 Image URL
url_75x75 string

The url string for a 75x75 pixel thumbnail of the image.

170x135 Image URL
url_170x135 string

The url string for a 170x135 pixel thumbnail of the image.

570xN Image URL
url_570xN string

The url string for a thumbnail of the image, no more than 570 pixels wide with variable height.

Full-size Image URL
url_fullxfull string

The url string for the full-size image, up to 3000 pixels in each dimension.

Full-size Image Height
full_height integer

The numeric height, measured in pixels, of the full-sized image referenced in url_fullxfull.

Full-size Image Width
full_width integer

The numeric width, measured in pixels, of the full-sized image referenced in url_fullxfull.

ListingImages

Represents a list of listing image resources, each of which contains the reference URLs and metadata for an image.

Name Path Type Description
Count
count integer

The number of results.

Results
results array of ListingImage

The list of requested resources.

ListingInventoryWithAssociations

A representation of a single listing's inventory record with associations

Name Path Type Description
Products
products array of ListingInventoryProduct

A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.

Price On Properties
price_on_property array of integer

An array of unique listing property ID integers for the properties that change product prices, if any. For example, if you charge specific prices for different sized products in the same listing, then this array contains the property ID for size.

Quantity On Properties
quantity_on_property array of integer

An array of unique listing property ID integers for the properties that change the quantity of the products, if any. For example, if you stock specific quantities of different colored products in the same listing, then this array contains the property ID for color.

SKU On Properties
sku_on_property array of integer

An array of unique listing property ID integers for the properties that change the product SKU, if any. For example, if you use specific skus for different colored products in the same listing, then this array contains the property ID for color.

ShopListing
listing ShopListing

A listing from a shop, which contains a product quantity, title, description, price, etc.

ListingInventoryProduct

A representation of a product for a listing.

Name Path Type Description
Product ID
product_id integer

The numeric ID for a specific product purchased from a listing.

SKU
sku string

The SKU string for the product

Is Deleted
is_deleted boolean

When true, someone deleted this product.

Offerings
offerings array of ListingInventoryProductOffering

A list of product offering entries for this product.

Property Values
property_values array of ListingPropertyValue

A list of property value entries for this product.

ListingInventoryProductOffering

A representation of an offering for a listing.

Name Path Type Description
Offering ID
offering_id integer

The ID for the product offering

Quantity
quantity integer

The quantity the product offering

Is Enabled
is_enabled boolean

Whether or not the offering can be shown to buyers.

Is Deleted
is_deleted boolean

Whether or not the offering has been deleted.

Money
price Money

A representation of an amount of money.

ListingPropertyValue

A representation of structured data values.

Name Path Type Description
Property ID
property_id integer

The numeric ID of the Property.

Name
property_name string

The name of the Property.

Scale ID
scale_id integer

The numeric ID of the scale (if any).

Scale Name
scale_name string

The label used to describe the chosen scale (if any).

Value IDs
value_ids array of integer

The numeric IDs of the property values

Values
values array of string

The property values

ListingInventory

A representation of a single listing's inventory record.

Name Path Type Description
Products
products array of ListingInventoryProduct

A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.

Price On Properties
price_on_property array of integer

An array of unique listing property ID integers for the properties that change product prices, if any. For example, if you charge specific prices for different sized products in the same listing, then this array contains the property ID for size.

Quantity On Properties
quantity_on_property array of integer

An array of unique listing property ID integers for the properties that change the quantity of the products, if any. For example, if you stock specific quantities of different colored products in the same listing, then this array contains the property ID for color.

SKU On Properties
sku_on_property array of integer

An array of unique listing property ID integers for the properties that change the product SKU, if any. For example, if you use specific skus for different colored products in the same listing, then this array contains the property ID for color.

ShopListingsWithAssociations

A set of shop listing resources with associations.

Name Path Type Description
Count
count integer

The number of shop listing resources found.

Results
results array of ShopListing

The shop listing resources found.

ListingPropertyValues

Represents several listing property values.

Name Path Type Description
Count
count integer

The number of shop listing resources found.

Results
results array of ListingPropertyValue

The shop listing resources found.

ShopReceiptTransactions

A set of shop receipt transaction resources

Name Path Type Description
Count
count integer

The number of shop receipt transaction resources found.

Results
results array of ShopReceiptTransaction

The shop receipt transaction resources found.

ShopReceiptTransaction

A transaction object associated with a shop receipt. Etsy generates one transaction per listing purchased as recorded on the order receipt.

Name Path Type Description
Transaction ID
transaction_id integer

The unique numeric ID for a transaction.

Title
title string

The title string of the listing purchased in this transaction.

Description
description string

The description string of the listing purchased in this transaction.

Seller User ID
seller_user_id integer

The numeric user ID for the seller in this transaction.

Buyer User ID
buyer_user_id integer

The numeric user ID for the buyer in this transaction.

Created Timestamp
create_timestamp integer

The transaction's creation date and time, in epoch seconds.

Paid Timestamp
paid_timestamp integer

The transaction's paid date and time, in epoch seconds.

Shipped Timestamp
shipped_timestamp integer

The transaction's shipping date and time, in epoch seconds.

Quantity
quantity integer

The numeric quantity of products purchased in this transaction.

Listing Image ID
listing_image_id integer

The numeric ID of the primary listing image for this transaction.

Receipt ID
receipt_id integer

The numeric ID for the receipt associated to this transaction.

Is Digital
is_digital boolean

When true, the transaction recorded the purchase of a digital listing.

File Data
file_data string

A string describing the files purchased in this transaction.

Listing ID
listing_id integer

The numeric ID for the listing associated to this transaction.

Transaction Type
transaction_type string

The type string for the transaction, usually listing

Product ID
product_id integer

The numeric ID for a specific product purchased from a listing.

Money
price Money

A representation of an amount of money.

Money
shipping_cost Money

A representation of an amount of money.

ListingTranslation

Represents the translation data for a Listing.

Name Path Type Description
Listing ID
listing_id integer

The numeric ID for the Listing.

Language
language string

The IETF language tag (e.g. 'fr') for the language of this translation.

Title
title string

The title of the Listing of this Translation.

Description
description string

The description of the Listing of this Translation.

Tags
tags array of string

The tags of the Listing of this Translation.

ListingVariationImages

Represents several listing variation images.

Name Path Type Description
Count
count integer

The count of variation images.

Results
results array of ListingVariationImage

The variation images results.

ListingVariationImage

A representation of the associations of variations and images on a listing.

Name Path Type Description
Property ID
property_id integer

The numeric ID of the Property.

Value ID
value_id integer

The numeric ID of the Value.

Image ID
image_id integer

The numeric ID of the Image.

PaymentAccountLedgerEntries

A set of payment account ledger entry resources

Name Path Type Description
Count
count integer

The number of payment account ledger entry resources found.

Results
results array of PaymentAccountLedgerEntry

The payment account ledger entry resources found.

PaymentAccountLedgerEntry

Represents an entry in a shop's ledger.

Name Path Type Description
Entry ID
entry_id integer

The ledger entry's numeric ID.

Ledger ID
ledger_id integer

The ledger's numeric ID.

Sequence Number
sequence_number integer

The sequence allows ledger entries to be sorted chronologically. The higher the sequence, the more recent the entry.

Amount
amount integer

The amount of money credited to the ledger.

Currency
currency string

The currency of the entry on the ledger.

Description
description string

Details what kind of ledger entry this is: a payment, refund, reversal of a failed refund, disbursement, returned disbursement, recoupment, miscellaneous credit, miscellaneous debit, or bill payment.

Balance
balance integer

The amount of money in the shop's ledger the moment after this entry was applied.

Created Date
create_date integer

The date and time the ledger entry was created in Epoch seconds..

Payments

Represents several payments made with Etsy Payments. All monetary amounts are in USD pennies unless otherwise specified.

Name Path Type Description
Count
count integer

The number of payments in the response.

Results
results array of Payment

A list of payments.

Payment

Represents a payment made with Etsy Payments. All monetary amounts are in USD pennies unless otherwise specified.

Name Path Type Description
Payment ID
payment_id integer

A unique numeric ID for a payment to a specific Etsy shop.

Buyer User ID
buyer_user_id integer

The numeric ID for the user who paid the purchase.

Shop ID
shop_id integer

The unique positive non-zero numeric ID for an Etsy Shop.

Receipt ID
receipt_id integer

The numeric ID for the receipt associated to this transaction.

Money
amount_gross Money

A representation of an amount of money.

Money
amount_fees Money

A representation of an amount of money.

Money
amount_net Money

A representation of an amount of money.

Money
posted_gross Money

A representation of an amount of money.

Money
posted_fees Money

A representation of an amount of money.

Money
posted_net Money

A representation of an amount of money.

Money
adjusted_gross Money

A representation of an amount of money.

Money
adjusted_fees Money

A representation of an amount of money.

Money
adjusted_net Money

A representation of an amount of money.

Currency
currency string

The ISO (alphabetic) code string for the payment's currency.

Shop Currency
shop_currency string

The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.

Buyer Currency
buyer_currency string

The currency string of the buyer.

User Shipping ID
shipping_user_id integer

The numeric ID of the user to which the seller ships the order.

Shipping Address ID
shipping_address_id integer

The numeric id identifying the shipping address.

Billing Address ID
billing_address_id integer

The numeric ID identifying the billing address of the buyer.

Status
status string

A string indicating the current status of the payment, most commonly settled or authed.

Shipped Timestamp
shipped_timestamp integer

The transaction's shipping date and time, in epoch seconds.

Created Timestamp
create_timestamp integer

The transaction's creation date and time, in epoch seconds.

Update Timestamp
update_timestamp integer

The date and time of the last change to the payment adjustment in epoch seconds.

Payment Adjustments
payment_adjustments array of PaymentAdjustment

List of refund objects on an Etsy Payments transaction. All monetary amounts are in USD pennies unless otherwise specified.

PaymentAdjustment

Represents a refund, which applies to a prior Etsy payment. All monetary amounts are in USD pennies unless otherwise specified.

Name Path Type Description
Payment Adjustment ID
payment_adjustment_id integer

The numeric ID for a payment adjustment.

Payment ID
payment_id integer

A unique numeric ID for a payment to a specific Etsy shop.

Status
status string

The status string of the payment adjustment.

Is Success
is_success boolean

When true, the payment adjustment was or is likely to complete successfully.

User ID
user_id integer

The numeric ID for the user (seller) fulfilling the purchase.

Reason Code
reason_code string

A human-readable string describing the reason for the refund.

Total Adjustment Amount
total_adjustment_amount integer

The total numeric amount of the refund in the payment currency.

Shop Total Adjustment Amount
shop_total_adjustment_amount integer

The numeric amount of the refund in the shop currency.

Total Adjustment Amount
buyer_total_adjustment_amount integer

The numeric amount of the refund in the buyer currency.

Total Fee Adjustment Amount
total_fee_adjustment_amount integer

The numeric amount of card processing fees associated with a payment adjustment.

Created Timestamp
create_timestamp integer

The transaction's creation date and time, in epoch seconds.

Update Timestamp
update_timestamp integer

The date and time of the last change to the payment adjustment in epoch seconds.

Pong

A confirmation that the current application has access to the Open API

Name Path Type Description
Application ID
application_id integer

The authenticated application's ID

ShopReceipt

The record of a purchase from a shop. Shop receipts display monetary values using the shop's currency.

Name Path Type Description
Receipt ID
receipt_id integer

The numeric ID for the receipt associated to this transaction.

Receipt Type
receipt_type integer

The numeric value for the Etsy channel that serviced the purchase: 0 for Etsy.com, 1 for a Pattern shop.

Seller User ID
seller_user_id integer

The numeric ID for the user (seller) fulfilling the purchase.

Seller's Email Address
seller_email string

The email address string for the seller of the listing.

Buyer User ID
buyer_user_id integer

The numeric ID for the user making the purchase.

Buyer's Email Address
buyer_email string

The email address string for the buyer of the listing.

Name
name string

The name string for the recipient in the shipping address.

First Address Line
first_line string

The first address line string for the recipient in the shipping address.

Second Address Line
second_line string

The optional second address line string for the recipient in the shipping address.

City
city string

The city string for the recipient in the shipping address.

State
state string

The state string for the recipient in the shipping address.

Zip Code
zip string

The zip code string (not necessarily a number) for the recipient in the shipping address.

Formatted Address
formatted_address string

The formatted shipping address string for the recipient in the shipping address.

Country Code ISO
country_iso string

The ISO-3166 alpha-2 country code string for the recipient in the shipping address.

Payment Method
payment_method string

The payment method string identifying purchaser's payment method, which must be one of: 'cc' (credit card), 'paypal', 'check', 'mo' (money order), 'bt' (bank transfer), 'other', 'ideal', 'sofort', 'apple_pay', 'google', 'android_pay', 'google_pay', 'klarna', 'k_pay_in_4' (klarna), or 'k_financing' (klarna).

Payment Email Address
payment_email string

The email address string for the email address to which to send payment confirmation

Message from Seller
message_from_seller string

An optional message string from the seller.

Message from Buyer
message_from_buyer string

An optional message string from the buyer.

Message from Payment System
message_from_payment string

The machine-generated acknowledgement string from the payment system.

Is Paid
is_paid boolean

When true, buyer paid for this purchase.

Is Shipped
is_shipped boolean

When true, seller shipped the products.

Created Timestamp
create_timestamp integer

The receipt's creation time, in epoch seconds.

Update Timestamp
update_timestamp integer

The time of the last update to the receipt, in epoch seconds.

Gift Message
gift_message string

A gift message string the buyer requests delivered with the product.

Money
grandtotal Money

A representation of an amount of money.

Money
subtotal Money

A representation of an amount of money.

Money
total_price Money

A representation of an amount of money.

Money
total_shipping_cost Money

A representation of an amount of money.

Money
total_tax_cost Money

A representation of an amount of money.

Money
total_vat_cost Money

A representation of an amount of money.

Money
discount_amt Money

A representation of an amount of money.

Money
gift_wrap_price Money

A representation of an amount of money.

Shipments
shipments array of ShopReceiptShipment

A list of shipment statements for this receipt.

ShopReceiptShipment

The record of one shipment event for a ShopReceipt. A receipt may have many ShopReceiptShipment records.

Name Path Type Description
Receipt Shipping ID
receipt_shipping_id integer

The unique numeric ID of a Shop Receipt Shipment record.

Shipment Notification Timestamp
shipment_notification_timestamp integer

The time at which Etsy notified the buyer of the shipment event, in epoch seconds.

Carrier Name
carrier_name string

The name string for the carrier/company responsible for delivering the shipment.

Tracking Code
tracking_code string

The tracking code string provided by the carrier/company for the shipment.

ShopReceipts

The receipts for a specific Shop.

Name Path Type Description
Count
count integer

The number of Shop Receipts found.

Results
results array of ShopReceipt

List of Shop Receipt resources found, with all Shop Receipt fields for each resource.

TransactionReviews

A set of transaction review records left by Users.

Name Path Type Description
Count
count integer

The number of TransactionReview resources found.

Results
results array of TransactionReview

The TransactionReview resources found.

TransactionReview

A transaction review record left by a User.

Name Path Type Description
Shop ID
shop_id integer

The shop's numeric ID.

Listing ID
listing_id integer

The ID of the shop listing that the TransactionReview belongs to.

Buyer User ID
buyer_user_id integer

The numeric ID of the user who was the buyer in this transaction. Note: This field may be absent, depending on the buyer's privacy settings.

Rating
rating integer

Rating value on scale from 1 to 5

Review Message
review string

A message left by the author, explaining the feedback.

Language
language string

The language of the TransactionReview

Fullsize Image URL
image_url_fullxfull string

The url to a photo provided with the feedback, dimensions fullxfull. Note: This field may be absent, depending on the buyer's privacy settings.

Created Timestamp
create_timestamp integer

The date and time the TransactionReview was created in epoch seconds.

Update Timestamp
update_timestamp integer

The date and time the TransactionReview was updated in epoch seconds.

SellerTaxonomyNodes

A list of taxonomy nodes from the seller taxonomy tree.

Name Path Type Description
Count
count integer

The number of results.

Results
results array of SellerTaxonomyNode

The list of requested resources.

SellerTaxonomyNode

A taxonomy node in the seller taxonomy tree.

Name Path Type Description
ID
id integer

The unique numeric ID of an Etsy taxonomy node, which is a metadata category for listings organized into the seller taxonomy hierarchy tree. For example, the shoes taxonomy node (ID: 1429, level: 1) is higher in the hierarchy than girls' shoes (ID: 1440, level: 2). The taxonomy nodes assigned to a listing support access to specific standardized product scales and properties. For example, listings assigned the taxonomy nodes shoes or girls' shoes support access to the EU shoe size scale with its associated property names and IDs for EU shoe sizes, such as property value_id:1394, and name:38.

Level
level integer

The integer depth of this taxonomy node in the seller taxonomy tree, with roots at level 0.

Name
name string

The name string for this taxonomy node.

Parent ID
parent_id integer

The numeric taxonomy ID of the parent of this node.

Children
children array of SellerTaxonomyNode

An array of taxonomy nodes for all the direct children of this taxonomy node in the seller taxanomy tree.

Taxonomy Path IDs
full_path_taxonomy_ids array of integer

An array of taxonomy IDs including this node and all of its direct parents in the seller taxonomy tree up to a root node. They are listed in order from root to leaf.

TaxonomyNodeProperties

A list of product property definitions.

Name Path Type Description
Count
count integer

The number of results.

Results
results array of TaxonomyNodeProperty

The list of requested resources.

TaxonomyNodeProperty

A product property definition.

Name Path Type Description
Property ID
property_id integer

The unique numeric ID of this product property.

Name
name string

The name string for this taxonomy node.

Display Name
display_name string

The human-readable product property name string.

Scales
scales array of TaxonomyPropertyScale

A list of available scales.

Is Required
is_required boolean

When true, listings assigned eligible taxonomy IDs require this property.

Supports Attributes
supports_attributes boolean

When true, you can use this property in listing attributes.

Supports Variations
supports_variations boolean

When true, you can use this property in listing variations.

Is Multivalued
is_multivalued boolean

When true, you can assign multiple property values to this property

Possible Values
possible_values array of TaxonomyPropertyValue

A list of supported property value strings for this property.

Selected Values
selected_values array of TaxonomyPropertyValue

A list of property value strings automatically and always selected for the given property.

TaxonomyPropertyScale

A scale defnining the assignable increments for the property values available to specific product properties.

Name Path Type Description
Scale ID
scale_id integer

The unique numeric ID of a scale.

Display Name
display_name string

The name string for a scale.

Description
description string

The description string for a scale.

TaxonomyPropertyValue

A property value for a specific product property, which may also employ a specific scale.

Name Path Type Description
Value ID
value_id integer

The numeric ID of this property value.

Name
name string

The name string of this property value.

Scale ID
scale_id integer

The numeric scale ID of the scale to which this property value belongs.

Equal To
equal_to array of integer

A list of numeric property value IDs this property value is equal to (if any).

ShippingCarriers

Represents several ShippingCarriers.

Name Path Type Description
count
count integer
results
results array of ShippingCarrier

ShippingCarrier

A supported shipping carrier, which is used to calculate an Estimated Delivery Date.

Name Path Type Description
Shipping Carrier ID
shipping_carrier_id integer

The numeric ID of this shipping carrier.

Name
name string

The name of this shipping carrier.

Domestic Classes
domestic_classes array of ShippingCarrierMailClass

Set of domestic mail classes of this shipping carrier.

International Classes
international_classes array of ShippingCarrierMailClass

Set of international mail classes of this shipping carrier.

ShippingCarrierMailClass

A shipping carrier's mail class, which is used to calculate an Estimated Delivery Date.

Name Path Type Description
Mail Class ID
mail_class_key string

The unique identifier of this mail class.

Name
name string

The name of this mail class.

Shops

A set of Shop records.

Name Path Type Description
Count
count integer

The total number of Shops

Results
results array of Shop

The Shop resources.

ShopSection

A section within a shop, into which a user can sort listings.

Name Path Type Description
Shop Section ID
shop_section_id integer

The numeric ID of a section in a specific Etsy shop.

Title
title string

The title string for a shop section.

Rank
rank integer

The positive non-zero numeric position of this section in the section display order for a shop, with rank 1 sections appearing first.

User ID
user_id integer

The numeric ID of the user who owns this shop section.

Active Listing Count
active_listing_count integer

The number of active listings in one section of a specific Etsy shop.

ShopSections

All the sections in a sprecific Shop.

Name Path Type Description
Count
count integer

The number of results.

Results
results array of ShopSection

The list of requested resources.

ShopShippingProfile

Represents a profile used to set a listing's shipping information. Please note that it's not possible to create calculated shipping templates via the API. However, you can associate calculated shipping profiles created from Shop Manager with listings using the API.

Name Path Type Description
Shipping Profile ID
shipping_profile_id integer

The numeric ID of the shipping profile.

Title
title string

The name string of this shipping profile.

User ID
user_id integer

The numeric ID for the user who owns the shipping profile.

Minimum Processing Days
min_processing_days integer

The minimum number of days for processing the listing.

Maximum Processing Days
max_processing_days integer

The maximum number of days for processing the listing.

Processing Days Label
processing_days_display_label string

Translated display label string for processing days.

Origin Country ISO
origin_country_iso string

The ISO code of the country from which the listing ships.

Is Deleted
is_deleted boolean

When true, someone deleted this shipping profile.

Shipping Profile Destinations
shipping_profile_destinations array of ShopShippingProfileDestination

A list of shipping profile destinations available for this shipping profile.

Shipping Profile Upgrades
shipping_profile_upgrades array of ShopShippingProfileUpgrade

A list of shipping profile upgrades available for this shipping profile.

Origin Postal Code
origin_postal_code string

The postal code string (not necessarily a number) for the location from which the listing ships.

ProfileType
profile_type ProfileType

ShopShippingProfileDestination

Represents a shipping destination assigned to a shipping profile.

Name Path Type Description
Shipping Profile Destination ID
shipping_profile_destination_id integer

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

Shipping Profile ID
shipping_profile_id integer

The numeric ID of the shipping profile.

Origin Country ISO
origin_country_iso string

The ISO code of the country from which the listing ships.

Destination Country ISO
destination_country_iso string

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region

DestinationRegion
destination_region DestinationRegion

The code of the region to which the listing ships. A region represents a set of countries. Supported regions are Europe Union and Non-Europe Union (countries in Europe not in EU). If none, request sets destination to destination_country_iso, or everywhere if destination_country_iso is also null

Money
primary_cost Money

A representation of an amount of money.

Money
secondary_cost Money

A representation of an amount of money.

Shipping Carrier ID
shipping_carrier_id integer

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date.

Mail Class
mail_class string

The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date.

Minimum Delivery Days
min_delivery_days integer

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped.

Maximum Delivery Days
max_delivery_days integer

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped.

ShopShippingProfileUpgrade

A representation of a shipping profile upgrade option.

Name Path Type Description
Shipping Profile ID
shipping_profile_id integer

The numeric ID of the base shipping profile.

Upgrade ID
upgrade_id integer

The numeric ID that is associated with a shipping upgrade

Upgrade Name
upgrade_name string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

Type
type Type

The type of the shipping upgrade. Domestic (0) or international (1).

Rank
rank integer

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

Language
language string

The IETF language tag for the language of the shipping profile. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

Money
price Money

A representation of an amount of money.

Money
secondary_price Money

A representation of an amount of money.

Shipping Carrier ID
shipping_carrier_id integer

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date.

Mail Class
mail_class string

The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date.

Minimum Delivery Days
min_delivery_days integer

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped.

Maximum Delivery Days
max_delivery_days integer

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped.

ShopShippingProfileDestinations

Represents a list of shipping destination objects.

Name Path Type Description
Count
count integer

The number of results.

Results
results array of ShopShippingProfileDestination

The list of requested resources.

ShopShippingProfileUpgrades

A list of shipping upgrade options.

Name Path Type Description
Count
count integer

The number of results.

Results
results array of ShopShippingProfileUpgrade

The list of requested resources.

UserAddress

Represents a user's address.

Name Path Type Description
User Address ID
user_address_id integer

The numeric ID of the user's address.

User ID
user_id integer

The user's numeric ID.

Name
name string

The user's name for this address.

First Address Line
first_line string

The first line of the user's address.

Second Address Line
second_line string

The second line of the user's address.

City
city string

The city field of the user's address.

State
state string

The state field of the user's address.

Zip Code
zip string

The zip code field of the user's address.

Country Code ISO
iso_country_code string

The ISO code of the country in this address.

Country
country_name string

The name of the user's country.

Is Default Shipping Address
is_default_shipping_address boolean

Is this the user's default shipping address.

UserAddresses

Represents several UserAddress records.

Name Path Type Description
Count
count integer

The number of UserAddress records being returned.

Results
results array of UserAddress

An array of UserAddress resources.

DestinationRegion

The code of the region to which the listing ships. A region represents a set of countries. Supported regions are Europe Union and Non-Europe Union (countries in Europe not in EU). If none, request sets destination to destination_country_iso, or everywhere if destination_country_iso is also null

The code of the region to which the listing ships. A region represents a set of countries. Supported regions are Europe Union and Non-Europe Union (countries in Europe not in EU). If none, request sets destination to destination_country_iso, or everywhere if destination_country_iso is also null

DestinationRegion
string

ItemDimensionsUnit

A string defining the units used to measure the dimensions of the product. Default value is null.

A string defining the units used to measure the dimensions of the product. Default value is null.

ItemDimensionsUnit
string

ItemWeightUnit

A string defining the units used to measure the weight of the product. Default value is null.

A string defining the units used to measure the weight of the product. Default value is null.

ItemWeightUnit
string

Occasion

An enumerated string indicating an occassion for which this product would make an appropriate gift. Default value is null.

An enumerated string indicating an occassion for which this product would make an appropriate gift. Default value is null.

Occasion
string

ProfileType

ProfileType
string

Recipient

An enumerated string indicating a person for whom this product would make an appropriate gift. Default value is null.

An enumerated string indicating a person for whom this product would make an appropriate gift. Default value is null.

Recipient
string

State

An enumerated string from any of: active or inactive. Note: Setting a draft listing to active will also publish the listing on etsy.com.

An enumerated string from any of: active or inactive. Note: Setting a draft listing to active will also publish the listing on etsy.com.

State
integer

Type

The type of the shipping upgrade. Domestic (0) or international (1).

The type of the shipping upgrade. Domestic (0) or international (1).

Type
integer

WhenMade

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

WhenMade
string

WhoMade

An enumerated string inidcated who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

An enumerated string inidcated who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

WhoMade
string