openapi: 3.0.2
info:
title: Etsy Open API v3 BuyerTaxonomy ShopListing API
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: developers@etsy.com
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: ShopListing
paths:
/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>
Creates 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>
Endpoint 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
default: 0
example: 0
- name: sort_on
in: query
description: 'The value to sort a search result of listings on. NOTES: a) `sort_on` only works when combined with one of the search options (keywords, region, etc.). b) when using `score` the returned results will always be in _descending_ order, regardless of the `sort_order` parameter.'
required: false
schema:
type: string
description: 'The value to sort a search result of listings on. NOTES: a) `sort_on` only works when combined with one of the search options (keywords, region, etc.). b) when using `score` the returned results will always be in _descending_ order, regardless of the `sort_order` parameter.'
enum:
- created
- price
- updated
- score
default: created
example: created
- name: sort_order
in: query
description: '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.).'
required: false
schema:
type: string
description: '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.).'
enum:
- asc
- ascending
- desc
- descending
- up
- down
default: desc
example: asc
- name: includes
in: query
description: An enumerated string that attaches a valid association. Acceptable inputs are 'Shipping', 'Shop', 'Images', 'User', 'Translations', 'Videos', 'Inventory' and 'Personalization'.
required: false
schema:
type: array
description: An enumerated string that attaches a valid association. Acceptable inputs are 'Shipping', 'Shop', 'Images', 'User', 'Translations', 'Videos', 'Inventory' and 'Personalization'.
items:
type: string
enum:
- Shipping
- Images
- Shop
- User
- Translations
- Inventory
- Videos
- Personalization
- BuyerPrice
default: null
example:
- Shipping
- 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
responses:
'200':
description: A list of Listings
content:
application/json:
schema:
$ref: '#/components/schemas/ShopListingsWithAssociations'
examples:
GetListingsByShop200Example:
summary: Default getListingsByShop 200 response
x-microcks-default: true
value:
count: 1
results:
- null
'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:
GetListingsByShop400Example:
summary: Default getListingsByShop 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:
GetListingsByShop401Example:
summary: Default getListingsByShop 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:
GetListingsByShop403Example:
summary: Default getListingsByShop 403 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:
GetListingsByShop500Example:
summary: Default getListingsByShop 500 response
x-microcks-default: true
value:
error: example string
security:
- api_key: []
oauth2:
- listings_r
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
summary: Etsy Get Listings by Shop
/v3/application/listings/{listing_id}:
delete:
operationId: deleteListing
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>
Open API V3 endpoint to delete a ShopListing. A ShopListing 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'
tags:
- ShopListing
parameters:
- name: listing_id
in: path
description: The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
required: true
schema:
type: integer
description: The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
format: int64
minimum: 1
example: 123456789
responses:
'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:
DeleteListing403Example:
summary: Default deleteListing 403 response
x-microcks-default: true
value:
error: example string
'409':
description: There was a request conflict with the current state of the target resource. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
DeleteListing409Example:
summary: Default deleteListing 409 response
x-microcks-default: true
value:
error: example string
'204':
description: The Listing resource was correctly deleted
'404':
description: A resource could not be found. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
DeleteListing404Example:
summary: Default deleteListing 404 response
x-microcks-default: true
value:
error: example string
'400':
descri
# --- truncated at 32 KB (195 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/etsy/refs/heads/main/openapi/etsy-shoplisting-api-openapi.yml