Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Etsy Open API v3 BuyerTaxonomy ShopListing Inventory 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 Inventory
paths:
/v3/application/listings/{listing_id}/inventory:
get:
operationId: getListingInventory
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>
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.'
tags:
- ShopListing Inventory
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
- name: show_deleted
in: query
description: A boolean value for inventory whether to include deleted products and their offerings. Default value is false.
required: false
schema:
type: boolean
description: A boolean value for inventory whether to include deleted products and their offerings. Default value is false.
example: true
- name: includes
in: query
description: An enumerated string that attaches a valid association. Default value is null.
required: false
schema:
type: string
description: An enumerated string that attaches a valid association. Default value is null.
enum:
- Listing
example: Listing
- 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 single listing inventory record.
content:
application/json:
schema:
$ref: '#/components/schemas/ListingInventoryWithAssociations'
examples:
GetListingInventory200Example:
summary: Default getListingInventory 200 response
x-microcks-default: true
value:
products:
- null
price_on_property:
- 1
quantity_on_property:
- 1
sku_on_property:
- 1
readiness_state_on_property:
- 1
listing: example
'404':
description: A resource could not be found. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetListingInventory404Example:
summary: Default getListingInventory 404 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:
GetListingInventory401Example:
summary: Default getListingInventory 401 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:
GetListingInventory400Example:
summary: Default getListingInventory 400 response
x-microcks-default: true
value:
error: example string
'422':
description: There was a problem processing your request. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetListingInventory422Example:
summary: Default getListingInventory 422 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:
GetListingInventory500Example:
summary: Default getListingInventory 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 Listing Inventory
put:
operationId: updateListingInventory
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>
Updates the inventory for a listing identified by a listing ID. The update fails if the supplied values for product sku, offering quantity, price, and/or processing profile 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.'
tags:
- ShopListing Inventory
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
- 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
- name: max_variations_supported
in: query
description: 'Coming soon: This parameter determines whether a third variation can be added to or updated for a listing. It accepts values of 2 or 3, where 3 enables third-variation support.'
required: false
schema:
type: string
description: 'Coming soon: This parameter determines whether a third variation can be added to or updated for a listing. It accepts values of 2 or 3, where 3 enables third-variation support.'
enum:
- '2'
- '3'
example: '2'
requestBody:
content:
application/json:
schema:
type: object
required:
- products
properties:
products:
type: array
description: A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.
items:
type: object
properties:
sku:
type:
- string
- 'null'
description: The SKU string for the product
property_values:
type: array
description: 'A list of property value entries for this product. Note: parenthesis characters (`(` and `)`) are not allowed.'
items:
type: object
properties:
property_id:
type: integer
description: The unique ID of an Etsy [listing property](/documentation/reference#operation/getListingInventory).
format: int64
minimum: 1
value_ids:
type: array
description: An array of unique IDs of Etsy [listing property](/documentation/reference#operation/getListingInventory) values.
items:
type: integer
format: int64
minimum: 1
scale_id:
type:
- integer
- 'null'
description: The numeric ID of a single Etsy.com measurement scale. For example, for shoe size, there are three `scale_id`s available - `UK`, `US/Canada`, and `EU`, where `US/Canada` has `scale_id` 19.
format: int64
minimum: 1
property_name:
type: string
description: The name of the property, in the requested locale language.
values:
type: array
description: 'A list of property value entries for this product. Note: parenthesis characters (`(` and `)`) are not allowed.'
items:
type: string
required:
- property_id
- value_ids
- values
offerings:
type: array
description: A list of product offering entries for this product.
items:
type: object
properties:
price:
type: number
description: The price of the product.
format: float
quantity:
type: integer
description: How many of this product are available?
is_enabled:
type: boolean
description: True if the offering is shown to buyers
readiness_state_id:
type:
- integer
- 'null'
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
minimum: 1
required:
- price
- quantity
- is_enabled
- readiness_state_id
required:
- offerings
price_on_property:
type: array
description: An array of unique [listing property](/documentation/reference#operation/getListingInventory) 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.
items:
type: integer
quantity_on_property:
type: array
description: An array of unique [listing property](/documentation/reference#operation/getListingInventory) 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.
items:
type: integer
sku_on_property:
type: array
description: An array of unique [listing property](/documentation/reference#operation/getListingInventory) 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.
items:
type: integer
readiness_state_on_property:
type:
- array
- 'null'
description: An array of unique [listing property](/documentation/reference#operation/getListingInventory) ID integers for the properties that change processing profile, if any. For example, if you need specific processing profiles for different colored products in the same listing, then this array contains the property ID for color.
items:
type: integer
format: int64
minimum: 1
examples:
UpdateListingInventoryRequestExample:
summary: Default updateListingInventory request
x-microcks-default: true
value:
products:
- sku: example string
property_values:
- property_id: 1
value_ids:
- {}
scale_id: 1
property_name: example string
values:
- {}
offerings:
- price: 1.0
quantity: 1
is_enabled: true
readiness_state_id: 1
price_on_property:
- 1
quantity_on_property:
- 1
sku_on_property:
- 1
readiness_state_on_property:
- 1
responses:
'200':
description: A single listing's inventory record.
content:
application/json:
schema:
$ref: '#/components/schemas/ListingInventory'
examples:
UpdateListingInventory200Example:
summary: Default updateListingInventory 200 response
x-microcks-default: true
value:
products:
- null
price_on_property:
- 1
quantity_on_property:
- 1
sku_on_property:
- 1
readiness_state_on_property:
- 1
'404':
description: A resource could not be found. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
UpdateListingInventory404Example:
summary: Default updateListingInventory 404 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:
UpdateListingInventory403Example:
summary: Default updateListingInventory 403 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:
UpdateListingInventory400Example:
summary: Default updateListingInventory 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:
UpdateListingInventory401Example:
summary: Default updateListingInventory 401 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:
UpdateListingInventory500Example:
summary: Default updateListingInventory 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 Update Listing Inventory
components:
schemas:
ErrorSchema:
type: object
x-resource-id: ErrorSchema
required:
- error
properties:
error:
type: string
example: example string
Money:
type: object
x-resource-id: Money
description: A representation of an amount of money.
properties:
amount:
type: integer
description: The amount of represented by this data.
example: 2500
divisor:
type: integer
description: The divisor to render the amount.
minimum: 0
example: 1
currency_code:
type: string
description: The ISO currency code for this data.
example: USD
ListingInventory:
type: object
x-resource-id: ListingInventory
description: A representation of a single listing's inventory record.
properties:
products:
type: array
description: A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.
items:
description: A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.
oneOf:
- $ref: '#/components/schemas/ListingInventoryProduct'
price_on_property:
type: array
description: An array of unique [listing property](/documentation/reference#operation/getListingInventory) 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.
items:
type: integer
quantity_on_property:
type: array
description: An array of unique [listing property](/documentation/reference#operation/getListingInventory) 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.
items:
type: integer
sku_on_property:
type: array
description: An array of unique [listing property](/documentation/reference#operation/getListingInventory) 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.
items:
type: integer
readiness_state_on_property:
type: array
description: An array of unique [listing property](/documentation/reference#operation/getListingInventory) ID integers for the properties that change processing profile, if any. For example, if you need specific processing profiles for different colored products in the same listing, then this array contains the property ID for color.
items:
type: integer
format: int64
minimum: 1
ListingInventoryProduct:
type: object
x-resource-id: ListingInventoryProduct
description: A representation of a product for a listing.
properties:
product_id:
type: integer
description: The numeric ID for a specific [product](/documentation/reference#tag/ShopListing-Product) purchased from a listing.
format: int64
minimum: 1
example: 567890123
sku:
type: string
description: The SKU string for the product
example: SKU-12345
is_deleted:
type: boolean
description: When true, someone deleted this product.
example: true
offerings:
type: array
description: A list of product offering entries for this product.
items:
description: A list of product offering entries for this product.
oneOf:
- $ref: '#/components/schemas/ListingInventoryProductOffering'
property_values:
type: array
description: 'A list of property value entries for this product. Note: parenthesis characters (`(` and `)`) are not allowed.'
items:
description: 'A list of property value entries for this product. Note: parenthesis characters (`(` and `)`) are not allowed.'
oneOf:
- $ref: '#/components/schemas/ListingPropertyValue'
ListingPropertyValue:
type: object
x-resource-id: ListingPropertyValue
description: A representation of structured data values.
properties:
property_id:
type: integer
description: The numeric ID of the Property.
format: int64
minimum: 1
example: 1
property_name:
type:
- string
- 'null'
description: The name of the Property.
example: Handmade Ceramic Mug
scale_id:
type:
- integer
- 'null'
description: The numeric ID of the scale (if any).
format: int64
minimum: 1
example: 1
scale_name:
type:
- string
- 'null'
description: The label used to describe the chosen scale (if any).
example: Handmade Ceramic Mug
value_ids:
type: array
description: The numeric IDs of the Property values
items:
type: integer
format: int64
minimum: 1
values:
type: array
description: The Property values
items:
type: string
ListingInventoryWithAssociations:
type: object
x-resource-id: ListingInventoryWithAssociations
description: A representation of a single listing's inventory record with associations
properties:
products:
type: array
description: A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.
items:
description: A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.
oneOf:
- $ref: '#/components/schemas/ListingInventoryProduct'
price_on_property:
type: array
description: An array of unique [listing property](/documentation/reference#operation/getListingInventory) 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.
items:
type: integer
quantity_on_property:
type: array
description: An array of unique [listing property](/documentation/reference#operation/getListingInventory) 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.
items:
type: integer
sku_on_property:
type: array
description: An array of unique [listing property](/documentation/reference#operation/getListingInventory) 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.
items:
type: integer
readiness_state_on_property:
type: array
description: An array of unique [listing property](/documentation/reference#operation/getListingInventory) ID integers for the properties that change processing profile, if any. For example, if you need specific processing profiles for different colored products in the same listing, then this array contains the property ID for color.
items:
type: integer
format: int64
minimum: 1
listing:
description: An enumerated string that attaches a valid association. Default value is null.
oneOf:
- $ref: '#/components/schemas/ShopListing'
example: example
ShopListing:
type: object
x-resource-id: ShopListing
description: A listing from a shop, which contains a product quantity, title, description, price, etc.
properties:
listing_id:
type: integer
description: The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
format: int64
minimum: 1
example: 123456789
user_id:
type: integer
description: The numeric ID for the [user](/documentation/reference#tag/User) posting the listing.
format: int64
minimum: 1
example: 456789
shop_id:
type: integer
description: The unique positive non-zero numeric ID for an Etsy Shop.
format: int64
minimum: 1
example: 123456
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.'
example: Handmade Ceramic Mug — Stoneware
description:
type: string
description: A description string of the product for sale in the listing.
example: Beautifully crafted handmade ceramic mug, kiln-fired in our Brooklyn studio.
state:
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
example: active
creation_timestamp:
type: integer
description: The listing's creation time, in epoch seconds.
minimum: 946684800
example: 1758153645
created_timestamp:
type: integer
description: The listing's creation time, in epoch seconds.
minimum: 946684800
example: 1758153645
ending_timestamp:
type: integer
description: The listing's expiration time, in epoch seconds.
minimum: 946684800
example: 1758153645
original_creation_timestamp:
type: integer
description: The listing's creation time, in epoch seconds.
minimum: 946684800
example: 1758153645
last_modified_timestamp:
type: integer
description: The time of the last update to the listing, in epoch seconds.
minimum: 946684800
example: 1758153645
updated_timestamp:
type: integer
description: The time of the last update to the listing, in epoch seconds.
minimum: 946684800
example: 1758153645
state_timestamp:
type:
- integer
- 'null'
description: The date and time of the last state change of this listing.
minimum: 946684800
example: 1758153645
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.'
minimum: 0
example: 1
shop_section_id:
type:
- integer
- 'null'
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/etsy/refs/heads/main/openapi/etsy-shoplisting-inventory-api-openapi.yml