openapi: 3.0.2
info:
title: Etsy Open API v3
description: <div class="wt-text-body-01"><p class="wt-pt-xs-2 wt-pb-xs-2">Etsy's Open API provides a simple RESTful interface for various Etsy.com features.</p><p class="wt-pb-xs-2">If you'd like to report an issue or provide feedback on the API design, <a target="_blank" class="wt-text-link wt-p-xs-0" href="https://github.com/etsy/open-api/discussions">please add an issue in Github</a>.</p></div>© 2021-2026 Etsy, Inc. All Rights Reserved. Use of this code is subject to Etsy's <a class='wt-text-link wt-p-xs-0' target='_blank' href='https://www.etsy.com/legal/api'>API Developer Terms of Use</a>.
termsOfService: https://www.etsy.com/legal/api
contact:
email: [email protected]
version: 3.0.0
x-generated-from: https://www.etsy.com/openapi/generated/oas/3.0.0.json
x-last-validated: '2026-05-30'
servers:
- url: https://openapi.etsy.com
description: Etsy Open API v3 base URL (per Etsy developer documentation; live calls also resolve at https://api.etsy.com/v3/application).
security:
- api_key: []
tags:
- name: User
- name: UserAddress
- name: Shop Receipt Transactions
- name: Other
- name: Shop
- name: Shop ShippingProfile
- name: Shop Section
- name: ShopListing
- name: Shop ProcessingProfiles
- name: Shop ProductionPartner
- name: Shop Return Policy
- name: Shop HolidayPreferences
- name: SellerTaxonomy
- name: Review
- name: Shop Receipt
- name: Payment
- name: Ledger Entry
- name: ShopListing Video
- name: ShopListing VariationImage
- name: ShopListing Translation
- name: ShopListing Personalization
- name: ShopListing Inventory
- name: ShopListing Offering
- name: ShopListing Product
- name: ShopListing Image
- name: ShopListing File
- name: BuyerTaxonomy
x-tagGroups:
- name: Listing Management
tags:
- BuyerTaxonomy
- SellerTaxonomy
- ShopListing
- ShopListing File
- ShopListing Image
- ShopListing Inventory
- ShopListing Offering
- ShopListing Personalization
- ShopListing Product
- ShopListing Translation
- ShopListing VariationImage
- ShopListing Video
- name: Other
tags:
- Other
- name: Payment Management
tags:
- Ledger Entry
- Payment
- name: Receipt Management
tags:
- Shop Receipt
- Shop Receipt Transactions
- name: Review Management
tags:
- Review
- name: Shipping Management
tags:
- Shop HolidayPreferences
- Shop ProcessingProfiles
- Shop ShippingProfile
- name: Shop Management
tags:
- Shop
- Shop ProductionPartner
- Shop Section
- name: Shop Policy Management
tags:
- Shop Return Policy
- name: User Management
tags:
- User
- UserAddress
paths:
/v3/application/buyer-taxonomy/nodes:
get:
operationId: getBuyerTaxonomyNodes
description: "<div class=\"wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3\"><span class=\"wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2\">General Release</span><a class=\"wt-text-link\" href=\"https://github.com/etsy/open-api/discussions\" target=\"_blank\" rel=\"noopener noreferrer\">Report bug</a></div><div class=\"wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3\"><p class=\"wt-text-body-01 banner-text\">This endpoint is ready for production use.</p></div>\n\nRetrieves the full hierarchy tree of buyer taxonomy nodes."
tags:
- BuyerTaxonomy
parameters: []
responses:
'200':
description: List the full hierarchy tree of buyer taxonomy nodes.
content:
application/json:
schema:
$ref: '#/components/schemas/BuyerTaxonomyNodes'
examples:
GetBuyerTaxonomyNodes200Example:
summary: Default getBuyerTaxonomyNodes 200 response
x-microcks-default: true
value:
count: 1
results:
-
'500':
description: The server encountered an internal error. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetBuyerTaxonomyNodes500Example:
summary: Default getBuyerTaxonomyNodes 500 response
x-microcks-default: true
value:
error: example string
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
summary: Etsy Get Buyer Taxonomy Nodes
/v3/application/buyer-taxonomy/nodes/{taxonomy_id}/properties:
get:
operationId: getPropertiesByBuyerTaxonomyId
description: "<div class=\"wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3\"><span class=\"wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2\">General Release</span><a class=\"wt-text-link\" href=\"https://github.com/etsy/open-api/discussions\" target=\"_blank\" rel=\"noopener noreferrer\">Report bug</a></div><div class=\"wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3\"><p class=\"wt-text-body-01 banner-text\">This endpoint is ready for production use.</p></div>\n\nRetrieves a list of product properties, with applicable scales and values, supported for a specific buyer taxonomy ID."
tags:
- BuyerTaxonomy
parameters:
- name: taxonomy_id
in: path
description: "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\"."
required: true
schema:
type: integer
description: "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\"."
format: int64
minimum: 1
example: 1234
responses:
'200':
description: A list of product properties, with applicable scales and values.
content:
application/json:
schema:
$ref: '#/components/schemas/BuyerTaxonomyNodeProperties'
examples:
GetPropertiesByBuyerTaxonomyId200Example:
summary: Default getPropertiesByBuyerTaxonomyId 200 response
x-microcks-default: true
value:
count: 1
results:
-
'404':
description: A resource could not be found. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetPropertiesByBuyerTaxonomyId404Example:
summary: Default getPropertiesByBuyerTaxonomyId 404 response
x-microcks-default: true
value:
error: example string
'400':
description: There was a problem with the request data. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetPropertiesByBuyerTaxonomyId400Example:
summary: Default getPropertiesByBuyerTaxonomyId 400 response
x-microcks-default: true
value:
error: example string
'500':
description: The server encountered an internal error. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetPropertiesByBuyerTaxonomyId500Example:
summary: Default getPropertiesByBuyerTaxonomyId 500 response
x-microcks-default: true
value:
error: example string
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
summary: Etsy Get Properties by Buyer Taxonomy Id
/v3/application/shops/{shop_id}/listings:
post:
operationId: createDraftListing
description: "<div class=\"wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3\"><span class=\"wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2\">General Release</span><a class=\"wt-text-link\" href=\"https://github.com/etsy/open-api/discussions\" target=\"_blank\" rel=\"noopener noreferrer\">Report bug</a></div><div class=\"wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3\"><p class=\"wt-text-body-01 banner-text\">This endpoint is ready for production use.</p></div>\n\nCreates a physical draft [listing](/documentation/reference#tag/ShopListing) product in a shop on the Etsy channel."
tags:
- ShopListing
parameters:
- name: shop_id
in: path
description: The unique positive non-zero numeric ID for an Etsy Shop.
required: true
schema:
type: integer
description: The unique positive non-zero numeric ID for an Etsy Shop.
format: int64
minimum: 1
example: 123456
- name: legacy
in: query
description: This parameter is needed to enable new parameters and response values related to processing profiles.
required: false
schema:
type: boolean
description: This parameter is needed to enable new parameters and response values related to processing profiles.
example: true
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- quantity
- title
- description
- price
- who_made
- when_made
- taxonomy_id
properties:
quantity:
type: integer
description: '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 [getListingInventory](/documentation/reference#operation/getListingInventory) endpoint.'
title:
type: string
description: "The listing's title string. When creating or updating a listing, 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:
type: string
description: A description string of the product for sale in the listing.
price:
type: number
description: 'The positive non-zero price of the product. (Sold product listings are private) Note: The price is the minimum possible price. The [`getListingInventory`](/documentation/reference/#operation/getListingInventory) method requests exact prices for available offerings.'
format: float
who_made:
type: string
description: An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.
enum:
- i_did
- someone_else
- collective
when_made:
type: string
description: 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'.
enum:
- made_to_order
- '2020_2026'
- '2010_2019'
- '2007_2009'
- before_2007
- '2000_2006'
- 1990s
- 1980s
- 1970s
- 1960s
- 1950s
- 1940s
- 1930s
- 1920s
- 1910s
- 1900s
- 1800s
- 1700s
- before_1700
taxonomy_id:
type: integer
description: The numerical taxonomy ID of the listing. See [SellerTaxonomy](/documentation/reference#tag/SellerTaxonomy) and [BuyerTaxonomy](/documentation/reference#tag/BuyerTaxonomy) for more information.
format: int64
minimum: 1
shipping_profile_id:
type: integer
description: The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.
format: int64
nullable: true
minimum: 1
return_policy_id:
type: integer
description: The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).
format: int64
nullable: true
minimum: 1
materials:
type: array
description: '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.'
nullable: true
items:
type: string
shop_section_id:
type: integer
description: The numeric ID of the [shop section](/documentation/reference#tag/Shop-Section) for this listing. Default value is null.
format: int64
nullable: true
minimum: 1
processing_min:
type: integer
description: The minimum number of days required to process this listing. Default value is null.
nullable: true
processing_max:
type: integer
description: The maximum number of days required to process this listing. Default value is null.
nullable: true
readiness_state_id:
type: integer
description: The numeric ID of the [processing profile](/documentation/reference#operation/getShopReadinessStateDefinition) associated with the listing. Returned only when the listing is `active` and of type `physical`, and the endpoint is either shop-scoped (path contains `shop_id`) or a single-listing request such as `getListing`. For every other case this field can be null.
format: int64
nullable: true
minimum: 1
tags:
type: array
description: "A comma-separated list of tag strings for the listing. When creating or updating a listing, valid tag strings contain only letters, numbers, whitespace characters, -, ', ™, ©, and ®. (regex: /[^\\p{L}\\p{Nd}\\p{Zs}\\-'™©®]/u) Default value is null."
nullable: true
items:
type: string
styles:
type: array
description: 'An array of style strings for this listing, each of which is free-form text string such as "Formal", or "Steampunk". When creating or updating a listing, the 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) Each style string is limited to 45 characters. Default value is null.'
nullable: true
items:
type: string
item_weight:
type: number
description: 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.
format: float
nullable: true
minimum: 0
maximum: 1.79769313486e+308
item_length:
type: number
description: 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.
format: float
nullable: true
minimum: 0
maximum: 1.79769313486e+308
item_width:
type: number
description: 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.
format: float
nullable: true
minimum: 0
maximum: 1.79769313486e+308
item_height:
type: number
description: The numeric height of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.
format: float
nullable: true
minimum: 0
maximum: 1.79769313486e+308
item_weight_unit:
type: string
description: A string defining the units used to measure the weight of the product. Default value is null.
nullable: true
enum:
- oz
- lb
- g
- kg
item_dimensions_unit:
type: string
description: A string defining the units used to measure the dimensions of the product. Default value is null.
nullable: true
enum:
- in
- ft
- mm
- cm
- m
- yd
- inches
is_personalizable:
type: boolean
description: '[DEPRECATED] When true, this listing is personalizable. The default value is false. NOTE: This field will be removed on Apr. 9th, 2026. See https://developers.etsy.com/documentation/tutorials/personalization-migration for migration details.'
personalization_is_required:
type: boolean
description: '[DEPRECATED] When true, this listing requires personalization. The default value is false. NOTE: This field will be removed on Apr. 9th, 2026. See https://developers.etsy.com/documentation/tutorials/personalization-migration for migration details.'
personalization_char_count_max:
type: integer
description: "[DEPRECATED] This is an integer value representing the maximum length for the personalization message entered by the buyer. Will only change if is_personalizable is 'true'. Note: This field will be removed on Apr. 9th, 2026. See https://developers.etsy.com/documentation/tutorials/personalization-migration for migration details."
personalization_instructions:
type: string
description: "[DEPRECATED] A string representing instructions for the buyer to enter the personalization. Will only change if is_personalizable is 'true'. Note: This field will be removed on Apr. 9th, 2026. See https://developers.etsy.com/documentation/tutorials/personalization-migration for migration details."
production_partner_ids:
type: array
description: An array of unique IDs of production partner ids.
nullable: true
items:
type: integer
format: int64
minimum: 1
image_ids:
type: array
description: An array of numeric image IDs of the images in a listing, which can include up to 20 images.
nullable: true
items:
type: integer
format: int64
minimum: 1
is_supply:
type: boolean
description: 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:
type: boolean
description: 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.
should_auto_renew:
type: boolean
description: When true, renews a listing for four months upon expiration.
is_taxable:
type: boolean
description: When true, applicable [shop](/documentation/reference#tag/Shop) tax rates apply to this listing at checkout.
type:
type: string
description: An enumerated type string that indicates whether the listing is physical or a digital download.
enum:
- physical
- download
- both
examples:
CreateDraftListingRequestExample:
summary: Default createDraftListing request
x-microcks-default: true
value:
quantity: 1
title: example string
description: example string
price: 1.0
who_made: i_did
when_made: made_to_order
taxonomy_id: 1
shipping_profile_id: 1
return_policy_id: 1
materials:
- example string
shop_section_id: 1
processing_min: 1
processing_max: 1
readiness_state_id: 1
tags:
- example string
styles:
- example string
item_weight: 1.0
item_length: 1.0
item_width: 1.0
item_height: 1.0
item_weight_unit: oz
item_dimensions_unit: in
is_personalizable: true
personalization_is_required: true
personalization_char_count_max: 1
personalization_instructions: example string
production_partner_ids:
- 1
image_ids:
- 1
is_supply: true
is_customizable: true
should_auto_renew: true
is_taxable: true
type: physical
responses:
'201':
description: A single ShopListing
content:
application/json:
schema:
$ref: '#/components/schemas/ShopListing'
examples:
CreateDraftListing201Example:
summary: Default createDraftListing 201 response
x-microcks-default: true
value:
listing_id: 123456789
user_id: 456789
shop_id: 123456
title: Handmade Ceramic Mug — Stoneware
description: Beautifully crafted handmade ceramic mug, kiln-fired in our Brooklyn studio.
state: active
creation_timestamp: 1758153645
created_timestamp: 1758153645
ending_timestamp: 1758153645
original_creation_timestamp: 1758153645
last_modified_timestamp: 1758153645
updated_timestamp: 1758153645
state_timestamp: 1758153645
quantity: 1
shop_section_id: 1
featured_rank: 1
url: https://www.etsy.com/listing/123456789
num_favorers: 1
non_taxable: true
is_taxable: true
is_customizable: true
is_personalizable: true
listing_type: physical
tags:
- example string
materials:
- example string
shipping_profile_id: 1
return_policy_id: 1
processing_min: 1
processing_max: 1
who_made: i_did
when_made: made_to_order
is_supply: true
item_weight: 0.5
item_weight_unit: oz
item_length: 1.0
item_width: 1.0
item_height: 1.0
item_dimensions_unit: in
is_private: true
style:
- example string
file_data: example string
has_variations: true
should_auto_renew: true
language: en-US
price: example
converted_price: example
taxonomy_id: 1234
readiness_state_id: 1
suggested_title: Handmade Ceramic Mug — Stoneware
'400':
description: There was a problem with the request data. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
CreateDraftListing400Example:
summary: Default createDraftListing 400 response
x-microcks-default: true
value:
error: example string
'401':
description: The request lacks valid authentication credentials. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
CreateDraftListing401Example:
summary: Default createDraftListing 401 response
x-microcks-default: true
value:
error: example string
'403':
description: The request attempted to perform an operation it is not allowed to. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
CreateDraftListing403Example:
summary: Default createDraftListing 403 response
x-microcks-default: true
value:
error: example string
'404':
description: A resource could not be found. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
CreateDraftListing404Example:
summary: Default createDraftListing 404 response
x-microcks-default: true
value:
error: example string
'500':
description: The server encountered an internal error. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
CreateDraftListing500Example:
summary: Default createDraftListing 500 response
x-microcks-default: true
value:
error: example string
security:
- api_key: []
oauth2:
- listings_w
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
summary: Etsy Create Draft Listing
get:
operationId: getListingsByShop
description: "<div class=\"wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3\"><span class=\"wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2\">General Release</span><a class=\"wt-text-link\" href=\"https://github.com/etsy/open-api/discussions\" target=\"_blank\" rel=\"noopener noreferrer\">Report bug</a></div><div class=\"wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3\"><p class=\"wt-text-body-01 banner-text\">This endpoint is ready for production use.</p></div>\n\nEndpoint to list Listings that belong to a Shop. Listings can be filtered using the 'state' param."
tags:
- ShopListing
parameters:
- name: shop_id
in: path
description: The unique positive non-zero numeric ID for an Etsy Shop.
required: true
schema:
type: integer
description: The unique positive non-zero numeric ID for an Etsy Shop.
format: int64
minimum: 1
example: 123456
- name: state
in: query
description: 'When _updating_ a listing, this value can be either `active` or `inactive`. Note: Setting a `draft` listing to `active` will also publish the listing on etsy.com and requires that the listing have an image set. Setting a `sold_out` listing to active will update the quantity to 1 and renew the listing on etsy.com.'
required: false
schema:
type: string
description: 'When _updating_ a listing, this value can be either `active` or `inactive`. Note: Setting a `draft` listing to `active` will also publish the listing on etsy.com and requires that the listing have an image set. Setting a `sold_out` listing to active will update the quantity to 1 and renew the listing on etsy.com.'
enum:
- active
- inactive
- sold_out
- draft
- expired
default: active
example: active
- name: limit
in: query
description: The maximum number of results to return.
required: false
schema:
type: integer
description: The maximum number of results to return.
minimum: 1
maximum: 100
default: 25
example: 25
- name: offset
in: query
description: The number of records to skip before selecting the first result.
required: false
schema:
type: integer
description: The number of records to skip before selecting the first result.
minimum: 0
# --- truncated at 32 KB (748 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/etsy/refs/heads/main/openapi/etsy-openapi-original.yml