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>&copy; 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':
          description: There was a problem with the request data. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                DeleteListing400Example:
                  summary: Default deleteListing 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:
                DeleteListing401Example:
                  summary: Default deleteListing 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:
                DeleteListing500Example:
                  summary: Default deleteListing 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      security:
      - api_key: []
        oauth2:
        - listings_d
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Delete Listing
    get:
      operationId: getListing
      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 a listing record by listing ID.'
      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
      - 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: language
        in: query
        description: 'The IETF language tag for the language of this translation. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`.'
        required: false
        schema:
          type: string
          description: 'The IETF language tag for the language of this translation. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`.'
          default: null
        example: en-US
      - 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: allow_suggested_title
        in: query
        description: This parameter will include in the response a suggested title for the listing, if one is available. Since suggestions are only available to the listing's owner, client must submit an oauth_access_token scoped to the owner of the listing.
        required: false
        schema:
          type: boolean
          description: This parameter will include in the response a suggested title for the listing, if one is available. Since suggestions are only available to the listing's owner, client must submit an oauth_access_token scoped to the owner of the listing.
        example: true
      responses:
        '200':
          description: A single Listing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopListingWithAssociations'
              examples:
                GetListing200Example:
                  summary: Default getListing 200 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
                    shipping_profile: example
                    user: example
                    shop: example
                    images:
                    - null
                    videos:
                    - null
                    inventory: example
                    production_partners:
                    - null
                    skus:
                    - example string
                    translations: example
                    views: 1
                    personalization: example
                    buyer_price: example
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetListing404Example:
                  summary: Default getListing 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:
                GetListing400Example:
                  summary: Default getListing 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:
                GetListing500Example:
                  summary: Default getListing 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Listing
  /v3/application/listings/active:
    get:
      operationId: findAllListingsActive
      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>


        A list of all active listings on Etsy paginated by their creation date. Without sort_order listings will be returned newest-first by default.'
      tags:
      - ShopListing
      parameters:
      - 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: keywords
        in: query
        description: Search term or phrase that must appear in all results.
        required: false
        schema:
          type: string
          description: Search term or phrase that must appear in all results.
          default: null
        example: example string
      - 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: min_price
        in: query
        description: The minimum price of listings to be returned by a search result.
        required: false
        schema:
          type: number
          description: The minimum price of listings to be returned by a search result.
          format: float
          default: null
        example: 25.0
      - name: max_price
        in: query
        description: The maximum price of listings to be returned by a search result.
        required: false
        schema:
          type: number
          description: The maximum price of listings to be returned by a search result.
          format: float
          default: null
        example: 25.0
      - name: taxonomy_id
        in: query
        description: The numerical taxonomy ID of the listing. See [SellerTaxonomy](/documentation/reference#tag/SellerTaxonomy) and [BuyerTaxonomy](/documentation/reference#tag/BuyerTaxonomy) for more information.
        required: false
        schema:
          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
          default: null
        example: 1234
      - name: shop_location
        in: query
        description: Filters by shop location. If location cannot be parsed, Etsy responds with an error.
        required: false
        schema:
          type: string
          description: Filters by shop location. If location cannot be parsed, Etsy responds with an error.
          default: null
        example: example string
      - 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: is_safe
        in: query
        description: When true, filters out mature/adult content from search results.
        required: false
        schema:
          type: boolean
          description: When true, filters out mature/adult content from search results.
        example: true
      - name: currency
        in: query
        description: The ISO 4217 alphabetic currency code (e.g., EUR, MXN) for price conversion. If provided, the listing price will be converted to this currency.
        required: false
        schema:
          type: string
          description: The ISO 4217 alphabetic currency code (e.g., EUR, MXN) for price conversion. If provided, the listing price will be converted to this currency.
          default: null
        example: example string
      - name: buyer_country
        in: query
        description: The ISO 3166-1 alpha-2 country code (e.g., DE, MX). Filters results to listings that ship to this country.
        required: false
        schema:
          type: string
          description: The ISO 3166-1 alpha-2 country code (e.g., DE, MX). Filters results to listings that ship to this country.
          format: ISO 3166-1 alpha-2
          default: null
        example: US
      responses:
        '200':
          description: A list of all active listings on Etsy paginated by their creation date. Without sort_order listings will be returned newest-first by default.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopListings'
              examples:
                FindAllListingsActive200Example:
                  summary: Default findAllListingsActive 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    results:
                    - null
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                FindAllListingsActive404Example:
                  summary: Default findAllListingsActive 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:
                FindAllListingsActive500Example:
                  summary: Default findAllListingsActive 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Find All Listings Active
  /v3/application/shops/{shop_id}/listings/active:
    get:
      operationId: findAllActiveListingsByShop
      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 a list of all active listings on Etsy in a specific shop, paginated by listing creation date.'
      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: 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: 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: 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: keywords
        in: query
        description: Search term or phrase that must appear in all results.
        required: false
        schema:
          type: string
          description: Search term or phrase that must appear in all results.
          default: null
        example: example string
      - 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: Retrieves a list of all active listings on Etsy in a specific shop, paginated by listing creation date.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopListings'
              examples:
                FindAllActiveListingsByShop200Example:
                  summary: Default findAllActiveListingsByShop 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    results:
                    - null
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                FindAllActiveListingsByShop404Example:
                  summary: Default findAllActiveListingsByShop 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:
                FindAllActiveListingsByShop400Example:
                  summary: Default findAllActiveListingsByShop 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:
                FindAllActiveListingsByShop500Example:
                  summary: Default findAllActiveListingsByShop 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Find All Active Listings by Shop
  /v3/application/listings/batch:
    get:
      operationId: getListingsByListingIds
      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>


        Allows to query multiple listing ids at once. Limit 100 ids maximum per query.'
      tags:
      - ShopListing
      parameters:
      - name: listing_ids
        in: query
        description: The list of numeric IDS for the listings in a specific Etsy shop.
        required: true
        schema:
          type: array
          description: The list of numeric IDS for the listings in a specific Etsy shop.
          items:
            type: integer
            format: int64
            minimum: 1
        example:
        - 123456789
      - 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
      - name: currency
        in: query
        description: The ISO 4217 alphabetic currency code (e.g., EUR, MXN) for price conversion. If provided, the listing price will be converted to this currency.
        required: false
        schema:
          type: string
          description: The ISO 4217 alphabetic currency code (e.g., EUR, MXN) for price conversion. If provided, the listing price will be converted to this currency.
          default: null
        example: example string
      - name: buyer_country
        in: query
        description: The ISO 3166-1 alpha-2 country code (e.g., GB, DE). Used for buyer-facing price calculations (VAT, inclusive shipping). Does not filter listings.
        required: false
        schema:
          type: string
          description: The ISO 3166-1 alpha-2 country code (e.g., GB, DE). Used for buyer-facing price calculations (VAT, inclusive shipping). Does not filter listings.
          format: ISO 3166-1 alpha-2
          default: null
        example: US
      responses:
        '200':
          description: A list of Listings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopListingsWithAssociations'
              examples:
                GetListingsByListingIds200Example:
                  summary: Default getListingsByListingIds 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:
                GetListingsByListingIds400Example:
                  summary: Default getListingsByListingIds 400 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:
                GetListingsByListingIds404Example:
                  summary: Default getListingsByListingIds 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:
                GetListingsByListingIds500Example:
                  summary: Default getListingsByListingIds 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Listings by Listing Ids
  /v3/application/shops/{shop_id}/listings/featured:
    get:
      operationId: getFeaturedListingsByShop
      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 Listings associated to a Shop that are featured.'
      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: 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: 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/ShopListings'
              examples:
                GetFeaturedListingsByShop200Example:
                  summary: Default getFeaturedListingsByShop 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:
                GetFeaturedListingsByShop400Example:
                  summary: Default getFeaturedListingsByShop 400 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:
                GetFeaturedListingsByShop403Example:
                  summary: Default getFeaturedListingsByShop 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:
                GetFeaturedListingsByShop500Example:
                  summary: Default getFeaturedListingsByShop 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Featured Listings by Shop
  /v3/application/shops/{shop_id}/listings/{listing_id}/properties/{property_id}:
    delete:
      operationId: deleteListingProperty
      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>


        Deletes a property for a Listing.'
      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: 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: property_id
        in: path
        description: The unique ID of an Etsy [listing property](/documentation/reference#operation/getListingProperties).
        required: true
        schema:
          type: integer
          description: The unique ID of an Etsy [listing property](/documentation/reference#operation/getListingProperties).
          format: int64
          minimum: 1
        example: 1
      responses:
        '204':
          description: The ListingProperty resource was correctly deleted
        '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:
                DeleteListingProperty403Example:
                  summary: Default deleteListingProperty 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:
                DeleteListingProperty404Example:
                  summary: Default deleteListingProperty 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:
                DeleteListingProperty400Example:
                  summary: Default deleteListingProperty 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:
                DeleteListingProperty401Example:
                  summary: Default deleteListingProperty 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:
                DeleteListingProperty500Example:
                  summary: Default deleteListingProperty 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 Delete Listing Property
    put:
      operationId: updateListingProperty
      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 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.'
      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: 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: property_id
        in: path
        description: The unique ID of an Etsy [listing property](/documentation/reference#operation/getListingProperties).
        required: true
        schema:
          type: integer
          description: The unique ID of an Etsy [listing property](/documentation/reference#operation/getListingProperties).
          format: int64
          minimum: 1
        example: 1
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - value_ids
              - values
              properties:
                value_ids:
                  type: array
                  description: An array of unique IDs of multiple Etsy [listing property](/documentation/reference#operation/getListingProperties) values. For example, if your listing is composed of different materials, then the value ID list contains value IDs for each material.
                  items:
                    type: integer
                    format: int64
                    minimum: 1
                values:
                  type: array
                  description: 'An array of value strings for multiple Etsy [listing property](/documentation/reference#operation/getListingProperties) values. For example, if your listing is painted in different colors, then the values array contains the color strings for each color. Note: parenthesis characters (`(` and `)`) are not allowed.'
                  items:
                    type: string
                scale_id:
                  type: integer
                  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
            examples:
              UpdateListingPropertyRequestExample:
                summary: Default updateListingProperty request
                x-microcks-default: true
                value:
                  value_ids:
                  - 1
                  values:
                  - example string
                  scale_id: 1
      responses:
        '200':
          description: A single listing property.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingPropertyValue'
              examples:
                UpdateListingProperty200Example:
                  summary: Default updateListingProperty 200 response
                  x-microcks-default: true
                  value:
                    property_id: 1
                    property_name: Handmade Ceramic Mug
                    scale_id: 1
                    scale_name: Handmade Ceramic Mug
                    value_ids:
                    - 1
                    values:
                    - 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:
                UpdateListingProperty403Example:
                  summary: Default updateListingProperty 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:
                UpdateListingProperty404Example:
                  summary: Default updateListingProperty 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:
                UpdateListingProperty400Example:
                  summary: Default updateListingProperty 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:
                UpdateListingProperty401Example:
                  summary: Default updateListingProperty 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:
                UpdateListingProperty500Example:
                  summary: Default updateListingProperty 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 Property
  /v3/application/listings/{listing_id}/properties/{property_id}:
    get:
      operationId: getListingProperty
      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--notificationTertiary wt-mr-xs-2"> Feedback only </span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Give feedback</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">Development for this endpoint is in progress. It will only return a 501 response.</p></div>


        Retrieves a listing''s property'
      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
      - name: property_id
        in: path
        description: The unique ID of an Etsy [listing property](/documentation/reference#operation/getListingProperties).
        required: true
        schema:
          type: integer
          description: The unique ID of an Etsy [listing property](/documentation/reference#operation/getListingProperties).
          format: int64
          minimum: 1
        example: 1
      responses:
        '200':
          description: A single ListingProperty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingPropertyValue'
              examples:
                GetListingProperty200Example:
                  summary: Default getListingProperty 200 response
                  x-microcks-default: true
                  value:
                    property_id: 1
                    property_name: Handmade Ceramic Mug
                    scale_id: 1
                    scale_name: Handmade Ceramic Mug
                    value_ids:
                    - 1
                    values:
                    - 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:
                GetListingProperty404Example:
                  summary: Default getListingProperty 404 response
                  x-microcks-default: true
                  value:
                    error: example string
        '501':
          description: This endpoint is not functional at this time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetListingProperty501Example:
                  summary: Default getListingProperty 501 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:
                GetListingProperty400Example:
                  summary: Default getListingProperty 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:
                GetListingProperty500Example:
                  summary: Default getListingProperty 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Listing Property
  /v3/application/shops/{shop_id}/listings/{listing_id}/properties:
    get:
      operationId: getListingProperties
      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>


        Get a listing''s properties'
      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: 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:
        '200':
          description: A Listing's Properties
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingPropertyValues'
              examples:
                GetListingProperties200Example:
                  summary: Default getListingProperties 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    results:
                    - property_id: 1
                      property_name: Handmade Ceramic Mug
                      scale_id: 1
                      scale_name: Handmade Ceramic Mug
                      value_ids:
                      - {}
                      values:
                      - {}
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetListingProperties404Example:
                  summary: Default getListingProperties 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:
                GetListingProperties400Example:
                  summary: Default getListingProperties 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:
                GetListingProperties500Example:
                  summary: Default getListingProperties 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Listing Properties
  /v3/application/shops/{shop_id}/listings/{listing_id}:
    patch:
      operationId: updateListing
      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 a listing, identified by a listing ID, for a specific shop identified by a shop ID. Note that this is a PATCH method type. When activating, or manually renewing a physical listing, the shipping profile referenced by the `shipping_profile_id`, and all of its fields, along with its entries and upgrades must be complete and valid. If the shipping profile is not complete and valid, we will throw an exception with an error message that guides the request sender to update whatever data is bad.   Digital listings that are not made to order must have a file upload associated with it to be activated. While the listing is a draft, shipping profile and file upload are not required in any case.'
      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: 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
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                image_ids:
                  type: array
                  description: An array of numeric image IDs of the images in a listing, which can include up to 20 images.
                  items:
                    type: integer
                    format: int64
                    minimum: 1
                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.
                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
                should_auto_renew:
                  type: boolean
                  description: When true, renews a listing for four months upon expiration.
                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). Required for active physical listings. This requirement does not apply to listings of EU-based shops.
                  format: int64
                  nullable: true
                  minimum: 1
                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.
                  nullable: true
                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_taxable:
                  type: boolean
                  description: When true, applicable [shop](/documentation/reference#tag/Shop) tax rates apply to this listing at checkout.
                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
                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
                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
                featured_rank:
                  type: integer
                  description: 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.
                  nullable: true
                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.'
                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
                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'.
                production_partner_ids:
                  type: array
                  description: An array of unique IDs of production partner ids.
                  nullable: true
                  items:
                    type: integer
                    format: int64
                    minimum: 1
                type:
                  type: string
                  description: An enumerated type string that indicates whether the listing is physical or a digital download.
                  nullable: true
                  enum:
                  - physical
                  - download
                  - both
            examples:
              UpdateListingRequestExample:
                summary: Default updateListing request
                x-microcks-default: true
                value:
                  image_ids:
                  - 1
                  title: example string
                  description: example string
                  materials:
                  - example string
                  should_auto_renew: true
                  shipping_profile_id: 1
                  return_policy_id: 1
                  shop_section_id: 1
                  item_weight: 1.0
                  item_length: 1.0
                  item_width: 1.0
                  item_height: 1.0
                  item_weight_unit: ''
                  item_dimensions_unit: ''
                  is_taxable: true
                  taxonomy_id: 1
                  tags:
                  - example string
                  who_made: i_did
                  when_made: made_to_order
                  featured_rank: 1
                  is_personalizable: true
                  personalization_is_required: true
                  personalization_char_count_max: 1
                  personalization_instructions: example string
                  state: active
                  is_supply: true
                  production_partner_ids:
                  - 1
                  type: physical
      responses:
        '200':
          description: A single ShopListing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopListing'
              examples:
                UpdateListing200Example:
                  summary: Default updateListing 200 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:
                UpdateListing400Example:
                  summary: Default updateListing 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:
                UpdateListing401Example:
                  summary: Default updateListing 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:
                UpdateListing403Example:
                  summary: Default updateListing 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:
                UpdateListing409Example:
                  summary: Default updateListing 409 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:
                UpdateListing404Example:
                  summary: Default updateListing 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:
                UpdateListing500Example:
                  summary: Default updateListing 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
  /v3/application/shops/{shop_id}/receipts/{receipt_id}/listings:
    get:
      operationId: getListingsByShopReceipt
      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>


        Gets all listings associated with a receipt.'
      tags:
      - ShopListing
      parameters:
      - name: receipt_id
        in: path
        description: The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.
        required: true
        schema:
          type: integer
          description: The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.
          format: int64
          minimum: 1
        example: 234567890
      - 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: 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: 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 set of ShopListing resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopListings'
              examples:
                GetListingsByShopReceipt200Example:
                  summary: Default getListingsByShopReceipt 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:
                GetListingsByShopReceipt400Example:
                  summary: Default getListingsByShopReceipt 400 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:
                GetListingsByShopReceipt403Example:
                  summary: Default getListingsByShopReceipt 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:
                GetListingsByShopReceipt404Example:
                  summary: Default getListingsByShopReceipt 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:
                GetListingsByShopReceipt401Example:
                  summary: Default getListingsByShopReceipt 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:
                GetListingsByShopReceipt500Example:
                  summary: Default getListingsByShopReceipt 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      security:
      - api_key: []
        oauth2:
        - transactions_r
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Listings by Shop Receipt
  /v3/application/shops/{shop_id}/policies/return/{return_policy_id}/listings:
    get:
      operationId: getListingsByShopReturnPolicy
      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>


        Gets all listings associated with a Return Policy.'
      tags:
      - ShopListing
      parameters:
      - name: return_policy_id
        in: path
        description: The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).
        required: true
        schema:
          type: integer
          description: The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).
          format: int64
          minimum: 1
        example: 1
      - 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
      responses:
        '200':
          description: A set of ShopListing resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopListings'
              examples:
                GetListingsByShopReturnPolicy200Example:
                  summary: Default getListingsByShopReturnPolicy 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:
                GetListingsByShopReturnPolicy400Example:
                  summary: Default getListingsByShopReturnPolicy 400 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:
                GetListingsByShopReturnPolicy403Example:
                  summary: Default getListingsByShopReturnPolicy 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:
                GetListingsByShopReturnPolicy404Example:
                  summary: Default getListingsByShopReturnPolicy 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:
                GetListingsByShopReturnPolicy401Example:
                  summary: Default getListingsByShopReturnPolicy 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:
                GetListingsByShopReturnPolicy500Example:
                  summary: Default getListingsByShopReturnPolicy 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 Return Policy
  /v3/application/shops/{shop_id}/shop-sections/listings:
    get:
      operationId: getListingsByShopSectionId
      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 all the listings from the section of a specific shop.'
      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: shop_section_ids
        in: query
        description: A list of numeric IDS for all sections in a specific Etsy shop.
        required: true
        schema:
          type: array
          description: A list of numeric IDS for all sections in a specific Etsy shop.
          items:
            type: integer
            format: int64
            minimum: 1
        example:
        - 1
      - 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: 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 from a shop section.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopListings'
              examples:
                GetListingsByShopSectionId200Example:
                  summary: Default getListingsByShopSectionId 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:
                GetListingsByShopSectionId400Example:
                  summary: Default getListingsByShopSectionId 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:
                GetListingsByShopSectionId500Example:
                  summary: Default getListingsByShopSectionId 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Listings by Shop Section Id
components:
  schemas:
    ListingVideo:
      type: object
      x-resource-id: ListingVideo
      description: Reference urls and metadata for a video associated with a specific listing.
      properties:
        video_id:
          type: integer
          description: The unique ID of a video associated with a listing.
          format: int64
          minimum: 1
          example: 1
        height:
          type: integer
          description: The video height dimension in pixels.
          example: 1
        width:
          type: integer
          description: The video width dimension in pixels.
          example: 1
        thumbnail_url:
          type: string
          description: The url of the video thumbnail.
          example: https://www.etsy.com/listing/123456789
        video_url:
          type: string
          description: The url of the video file.
          example: https://www.etsy.com/listing/123456789
        video_state:
          type: string
          description: The current state of a given video. Value is one of `active`, `inactive`, `deleted` or `flagged`.
          enum:
          - active
          - inactive
          - deleted
          - flagged
          default: active
          example: active
    ListingImage:
      type: object
      x-resource-id: ListingImage
      description: 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.
      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
        listing_image_id:
          type: integer
          description: The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.
          format: int64
          minimum: 1
          example: 1
        hex_code:
          type: string
          description: The webhex string for the image's average color, in webhex notation.
          nullable: true
          example: example string
        red:
          type: integer
          description: The numeric red value equal to the image's average red value, from 0-255 (RGB color).
          nullable: true
          minimum: 0
          example: 1
        green:
          type: integer
          description: The numeric red value equal to the image's average red value, from 0-255 (RGB color).
          nullable: true
          minimum: 0
          example: 1
        blue:
          type: integer
          description: The numeric red value equal to the image's average red value, from 0-255 (RGB color).
          nullable: true
          minimum: 0
          example: 1
        hue:
          type: integer
          description: The numeric hue equal to the image's average hue, from 0-360 (HSV color).
          nullable: true
          minimum: 0
          example: 1
        saturation:
          type: integer
          description: The numeric saturation equal to the image's average saturation, from 0-100 (HSV color).
          nullable: true
          minimum: 0
          example: 1
        brightness:
          type: integer
          description: The numeric brightness equal to the image's average brightness, from 0-100 (HSV color).
          nullable: true
          minimum: 0
          example: 1
        is_black_and_white:
          type: boolean
          description: When true, the image is in black & white.
          nullable: true
          example: true
        creation_tsz:
          type: integer
          description: The listing image's creation time, in epoch seconds.
          minimum: 0
          example: 1
        created_timestamp:
          type: integer
          description: The listing image's creation time, in epoch seconds.
          minimum: 0
          example: 1758153645
        rank:
          type: integer
          description: 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.
          minimum: 0
          example: 1
        url_75x75:
          type: string
          description: The url string for a 75x75 pixel thumbnail of the image.
          example: https://www.etsy.com/listing/123456789
        url_170x135:
          type: string
          description: The url string for a 170x135 pixel thumbnail of the image.
          example: https://www.etsy.com/listing/123456789
        url_570xN:
          type: string
          description: The url string for a thumbnail of the image, no more than 570 pixels wide with variable height.
          example: https://www.etsy.com/listing/123456789
        url_fullxfull:
          type: string
          description: The url string for the full-size image, up to 3000 pixels in each dimension.
          example: https://www.etsy.com/listing/123456789
        full_height:
          type: integer
          description: The numeric height, measured in pixels, of the full-sized image referenced in url_fullxfull.
          nullable: true
          minimum: 0
          example: 1
        full_width:
          type: integer
          description: The numeric width, measured in pixels, of the full-sized image referenced in url_fullxfull.
          nullable: true
          minimum: 0
          example: 1
        alt_text:
          type: string
          description: Alt text for the listing image. Max length 500 characters.
          nullable: true
          example: example string
    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
          description: The name of the Property.
          nullable: true
          example: Handmade Ceramic Mug
        scale_id:
          type: integer
          description: The numeric ID of the scale (if any).
          format: int64
          nullable: true
          minimum: 1
          example: 1
        scale_name:
          type: string
          description: The label used to describe the chosen scale (if any).
          nullable: true
          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
    ListingPropertyValues:
      type: object
      x-resource-id: ListingPropertyValues
      description: Represents several ListingPropertyValues.
      properties:
        count:
          type: integer
          minimum: 0
          example: 1
        results:
          type: array
          items:
            $ref: '#/components/schemas/ListingPropertyValue'
    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
    ShopListingWithAssociations:
      type: object
      x-resource-id: ShopListingWithAssociations
      description: A listing from a shop, which contains a product quantity, title, description, price, etc. and additional fields which represent associations.
      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
          description: The date and time of the last state change of this listing.
          nullable: true
          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
          description: The numeric ID of a section in a specific Etsy shop.
          format: int64
          nullable: true
          minimum: 1
          example: 1
        featured_rank:
          type: integer
          description: 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.
          example: 1
        url:
          type: string
          description: The full URL to the listing's page on Etsy.
          example: https://www.etsy.com/listing/123456789
        num_favorers:
          type: integer
          description: The number of users who marked this Listing a favorite.
          minimum: 0
          example: 1
        non_taxable:
          type: boolean
          description: When true, applicable [shop](/documentation/reference#tag/Shop) tax rates do not apply to this listing at checkout.
          example: true
        is_taxable:
          type: boolean
          description: When true, applicable [shop](/documentation/reference#tag/Shop) tax rates apply to this listing at checkout.
          example: true
        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.
          example: true
        is_personalizable:
          type: boolean
          description: When true, this listing is personalizable. The default value is false.
          example: true
        listing_type:
          type: string
          description: An enumerated type string that indicates whether the listing is physical or a digital download.
          enum:
          - physical
          - download
          - both
          example: physical
        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.'
          items:
            type: string
        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.'
          items:
            type: string
        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
          example: 1
        return_policy_id:
          type: integer
          description: The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).
          format: int64
          nullable: true
          minimum: 1
          example: 1
        processing_min:
          type: integer
          description: The minimum number of days required to process this listing. Default value is null.
          nullable: true
          minimum: 0
          example: 1
        processing_max:
          type: integer
          description: The maximum number of days required to process this listing. Default value is null.
          nullable: true
          minimum: 0
          example: 1
        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'.
          nullable: true
          enum:
          - i_did
          - someone_else
          - collective
          example: i_did
        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'.
          nullable: true
          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
          example: made_to_order
        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'.
          nullable: true
          example: true
        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
          example: 0.5
        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
          example: oz
        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
          example: 1.0
        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
          example: 1.0
        item_height:
          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
          example: 1.0
        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
          example: in
        is_private:
          type: boolean
          description: When true, this is a private listing intended for a specific buyer and hidden from shop view.
          example: true
        style:
          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.'
          items:
            type: string
        file_data:
          type: string
          description: A string describing the files attached to a digital listing.
          nullable: true
          example: example string
        has_variations:
          type: boolean
          description: When true, the listing has variations.
          example: true
        should_auto_renew:
          type: boolean
          description: When true, renews a listing for four months upon expiration.
          example: true
        language:
          type: string
          description: 'The IETF language tag for the default language of the listing. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`, `ru`.'
          nullable: true
          example: en-US
        price:
          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.'
          oneOf:
          - $ref: '#/components/schemas/Money'
          example: example
        converted_price:
          description: The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.
          oneOf:
          - $ref: '#/components/schemas/Money'
          nullable: true
          example: example
        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.
          nullable: true
          example: 1234
        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
          example: 1
        suggested_title:
          type: string
          description: A title string suggested by Etsy. Only available for a user's own listings, when allow_suggested_title param is present, and when a shop's language setting is English. Not all listings will have suggestions.
          nullable: true
          example: Handmade Ceramic Mug — Stoneware
        shipping_profile:
          description: An array of data representing the shipping profile resource.
          oneOf:
          - $ref: '#/components/schemas/ShopShippingProfile'
          nullable: true
          example: example
        user:
          description: Represents a single user of the site
          oneOf:
          - $ref: '#/components/schemas/User'
          nullable: true
          example: example
        shop:
          description: A shop created by an Etsy user.
          oneOf:
          - $ref: '#/components/schemas/Shop'
          nullable: true
          example: example
        images:
          type: array
          description: Represents a list of listing image resources, each of which contains the reference URLs and metadata for an image
          items:
            description: Represents a list of listing image resources, each of which contains the reference URLs and metadata for an image
            oneOf:
            - $ref: '#/components/schemas/ListingImage'
        videos:
          type: array
          description: The single video associated with a listing.
          items:
            description: The single video associated with a listing.
            oneOf:
            - $ref: '#/components/schemas/ListingVideo'
        inventory:
          description: An enumerated string that attaches a valid association. Default value is null.
          oneOf:
          - $ref: '#/components/schemas/ListingInventory'
          nullable: true
          example: example
        production_partners:
          type: array
          description: Represents a list of production partners for a shop.
          items:
            description: Represents a list of production partners for a shop.
            oneOf:
            - $ref: '#/components/schemas/ShopProductionPartner'
        skus:
          type: array
          description: A list of SKU strings for the listing. SKUs will only appear if the requesting user owns the shop and a valid matching OAuth 2 token is provided. When requested without the token it will be an empty array.
          items:
            type: string
        translations:
          description: A map of translations for the listing. Default value is a map of all supported languages keyed to null.
          oneOf:
          - $ref: '#/components/schemas/ListingTranslations'
          nullable: true
          example: example
        views:
          type: integer
          description: The number of times the listing has been viewed. This value is tabulated once per day and **only for active listings**, so the value is not real-time. If `0`, the listing has either not been viewed, not yet tabulated, was not active during the last tabulation or there was an error fetching the value. If a value is expected, call `getListing` to confirm the value.
          example: 1
        personalization:
          oneOf:
          - $ref: '#/components/schemas/Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_ListingPersonalization'
          nullable: true
          example: example
        buyer_price:
          description: The buyer-facing price for a listing, including VAT, inclusive shipping (UK), and active promotions. Requires buyer_country parameter. Shows base_price, shipping_cost, original_price (display price), and discounted_price if a promotion is active. Currently only supported on the /listings/batch endpoint.
          oneOf:
          - $ref: '#/components/schemas/ListingBuyerPrice'
          nullable: true
          example: example
    ShopListings:
      type: object
      x-resource-id: ShopListings
      description: A set of ShopListing resources.
      properties:
        count:
          type: integer
          description: The number of ShopListing resources found.
          minimum: 0
          example: 1
        results:
          type: array
          description: The ShopListing resources found.
          items:
            description: The ShopListing resources found.
            oneOf:
            - $ref: '#/components/schemas/ShopListing'
    Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_ListingPersonalization:
      type: object
      x-resource-id: Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_ListingPersonalization
      properties:
        personalization_questions:
          type: array
          items:
            $ref: '#/components/schemas/Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion'
    ShopShippingProfileUpgrade:
      type: object
      x-resource-id: ShopShippingProfileUpgrade
      description: A representation of a shipping profile upgrade option.
      properties:
        shipping_profile_id:
          type: integer
          description: The numeric ID of the base shipping profile.
          format: int64
          minimum: 1
          example: 1
        upgrade_id:
          type: integer
          description: The numeric ID that is associated with a shipping upgrade
          format: int64
          minimum: 1
          example: 1
        upgrade_name:
          type: string
          description: Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.
          example: Handmade Ceramic Mug
        type:
          type: integer
          description: The type of the shipping upgrade. Domestic (0) or international (1).
          enum:
          - 0
          - 1
          example: 0
        rank:
          type: integer
          description: 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.
          minimum: 0
          example: 1
        language:
          type: string
          description: 'The IETF language tag for the language of the shipping profile. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`'
          example: en-US
        price:
          description: Additional cost of adding the shipping upgrade.
          oneOf:
          - $ref: '#/components/schemas/Money'
          example: example
        secondary_price:
          description: Additional cost of adding the shipping upgrade for each additional item.
          oneOf:
          - $ref: '#/components/schemas/Money'
          example: example
        shipping_carrier_id:
          type: integer
          description: The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with `mail_class`** if `min_delivery_days` and `max_delivery_days` are null.
          nullable: true
          example: 1
        mail_class:
          type: string
          description: The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date. **Required with `shipping_carrier_id`** if `min_delivery_days` and `max_delivery_days` are null.
          nullable: true
          example: example string
        min_delivery_days:
          type: integer
          description: The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `max_delivery_days`** if `mail_class` is null.
          nullable: true
          minimum: 1
          maximum: 45
          example: 1
        max_delivery_days:
          type: integer
          description: The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `min_delivery_days`** if `mail_class` is null.
          nullable: true
          minimum: 1
          maximum: 45
          example: 1
    ShopShippingProfileDestination:
      type: object
      x-resource-id: ShopShippingProfileDestination
      description: Represents a shipping destination assigned to a shipping profile.
      properties:
        shipping_profile_destination_id:
          type: integer
          description: The numeric ID of the shipping profile destination in the [shipping profile](/documentation/reference#tag/Shop-ShippingProfile) associated with the listing.
          format: int64
          minimum: 1
          example: 1
        shipping_profile_id:
          type: integer
          description: The numeric ID of the shipping profile.
          format: int64
          minimum: 1
          example: 1
        origin_country_iso:
          type: string
          description: The ISO code of the country from which the listing ships.
          format: ISO 3166-1 alpha-2
          example: US
        destination_country_iso:
          type: string
          description: The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.
          example: US
        destination_region:
          type: string
          description: 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. Required if destination_country_iso is null or not provided.
          enum:
          - eu
          - non_eu
          - none
          example: eu
        primary_cost:
          description: The cost of shipping to this country/region alone, measured in the store's default currency.
          oneOf:
          - $ref: '#/components/schemas/Money'
          example: example
        secondary_cost:
          description: The cost of shipping to this country/region with another item, measured in the store's default currency.
          oneOf:
          - $ref: '#/components/schemas/Money'
          example: example
        shipping_carrier_id:
          type: integer
          description: The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with `mail_class`** if `min_delivery_days` and `max_delivery_days` are null.
          nullable: true
          example: 1
        mail_class:
          type: string
          description: The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date. **Required with `shipping_carrier_id`** if `min_delivery_days` and `max_delivery_days` are null.
          nullable: true
          example: example string
        min_delivery_days:
          type: integer
          description: The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `max_delivery_days`** if `mail_class` is null.
          nullable: true
          minimum: 1
          maximum: 45
          example: 1
        max_delivery_days:
          type: integer
          description: The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `min_delivery_days`** if `mail_class` is null.
          nullable: true
          minimum: 1
          maximum: 45
          example: 1
    ShopShippingProfile:
      type: object
      x-resource-id: ShopShippingProfile
      description: 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.
      properties:
        shipping_profile_id:
          type: integer
          description: The numeric ID of the shipping profile.
          format: int64
          minimum: 1
          example: 1
        title:
          type: string
          description: The name string of this shipping profile.
          nullable: true
          example: Handmade Ceramic Mug — Stoneware
        user_id:
          type: integer
          description: The numeric ID for the [user](/documentation/reference#tag/User) who owns the shipping profile.
          format: int64
          minimum: 1
          example: 456789
        origin_country_iso:
          type: string
          description: The ISO code of the country from which the listing ships.
          format: ISO 3166-1 alpha-2
          example: US
        is_deleted:
          type: boolean
          description: When true, someone deleted this shipping profile.
          example: true
        shipping_profile_destinations:
          type: array
          description: A list of [shipping profile destinations](/documentation/reference/#operation/createShopShippingProfileDestination) available for this shipping profile.
          items:
            description: A list of [shipping profile destinations](/documentation/reference/#operation/createShopShippingProfileDestination) available for this shipping profile.
            oneOf:
            - $ref: '#/components/schemas/ShopShippingProfileDestination'
        shipping_profile_upgrades:
          type: array
          description: A list of [shipping profile upgrades](/documentation/reference/#operation/createShopShippingProfileUpgrade) available for this shipping profile.
          items:
            description: A list of [shipping profile upgrades](/documentation/reference/#operation/createShopShippingProfileUpgrade) available for this shipping profile.
            oneOf:
            - $ref: '#/components/schemas/ShopShippingProfileUpgrade'
        origin_postal_code:
          type: string
          description: The postal code string (not necessarily a number) for the location from which the listing ships. Required if the `origin_country_iso` supports postal codes. See the [Fulfillment Tutorial docs](https://developer.etsy.com/documentation/tutorials/fulfillment/#countries-requiring-postal-codes) for more info
          nullable: true
          example: '11201'
        profile_type:
          type: string
          enum:
          - manual
          - calculated
          default: manual
          example: manual
        domestic_handling_fee:
          type: number
          description: The domestic handling fee added to buyer's shipping total - only available for calculated shipping profiles.
          format: float
          minimum: 0
          default: 0
          example: 1.0
        international_handling_fee:
          type: number
          description: The international handling fee added to buyer's shipping total - only available for calculated shipping profiles.
          format: float
          minimum: 0
          default: 0
          example: 1.0
    ListingTranslation:
      type: object
      x-resource-id: ListingTranslation
      description: Represents the translation data for a Listing.
      properties:
        listing_id:
          type: integer
          description: The numeric ID for the Listing.
          format: int64
          minimum: 1
          example: 123456789
        language:
          type: string
          description: The IETF language tag (e.g. 'fr') for the language of this translation.
          example: en-US
        title:
          type: string
          description: The title of the Listing of this Translation.
          nullable: true
          example: Handmade Ceramic Mug — Stoneware
        description:
          type: string
          description: The description of the Listing of this Translation.
          nullable: true
          example: Beautifully crafted handmade ceramic mug, kiln-fired in our Brooklyn studio.
        tags:
          type: array
          description: The tags of the Listing of this Translation.
          items:
            type: string
    ErrorSchema:
      type: object
      x-resource-id: ErrorSchema
      required:
      - error
      properties:
        error:
          type: string
          example: example string
    Shop:
      type: object
      x-resource-id: Shop
      description: A shop created by an Etsy user.
      properties:
        shop_id:
          type: integer
          description: The unique positive non-zero numeric ID for an Etsy Shop.
          format: int64
          minimum: 1
          example: 123456
        user_id:
          type: integer
          description: The numeric user ID of the [user](/documentation/reference#tag/User) who owns this shop.
          format: int64
          minimum: 1
          example: 456789
        shop_name:
          type: string
          description: The shop's name string.
          example: HandmadeCrafts
        create_date:
          type: integer
          description: The date and time this shop was created, in epoch seconds.
          minimum: 0
          example: 1
        created_timestamp:
          type: integer
          description: The date and time this shop was created, in epoch seconds.
          minimum: 0
          example: 1758153645
        title:
          type: string
          description: A brief heading string for the shop's main page.
          nullable: true
          example: Handmade Ceramic Mug — Stoneware
        announcement:
          type: string
          description: An announcement string to buyers that displays on the shop's homepage.
          nullable: true
          example: example string
        currency_code:
          type: string
          description: The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.
          example: USD
        is_vacation:
          type: boolean
          description: When true, this shop is not accepting purchases.
          example: true
        vacation_message:
          type: string
          description: The shop's message string displayed when `is_vacation` is true.
          nullable: true
          example: Thanks for your order! Shipping out tomorrow.
        sale_message:
          type: string
          description: A message string sent to users who complete a purchase from this shop.
          nullable: true
          example: Thanks for your order! Shipping out tomorrow.
        digital_sale_message:
          type: string
          description: A message string sent to users who purchase a digital item from this shop.
          nullable: true
          example: Thanks for your order! Shipping out tomorrow.
        update_date:
          type: integer
          description: The date and time of the last update to the shop, in epoch seconds.
          minimum: 0
          example: 1
        updated_timestamp:
          type: integer
          description: The date and time of the last update to the shop, in epoch seconds.
          minimum: 0
          example: 1758153645
        listing_active_count:
          type: integer
          description: The number of active listings in the shop.
          minimum: 0
          example: 1
        digital_listing_count:
          type: integer
          description: The number of digital listings in the shop.
          minimum: 0
          example: 1
        login_name:
          type: string
          description: The shop owner's login name string.
          example: handmade_seller
        accepts_custom_requests:
          type: boolean
          description: When true, the shop accepts customization requests.
          example: true
        policy_welcome:
          type: string
          description: The shop's policy welcome string (may be blank).
          nullable: true
          example: example string
        policy_payment:
          type: string
          description: The shop's payment policy string (may be blank).
          nullable: true
          example: example string
        policy_shipping:
          type: string
          description: The shop's shipping policy string (may be blank).
          nullable: true
          example: example string
        policy_refunds:
          type: string
          description: The shop's refund policy string (may be blank).
          nullable: true
          example: example string
        policy_additional:
          type: string
          description: The shop's additional policies string (may be blank).
          nullable: true
          example: example string
        policy_seller_info:
          type: string
          description: The shop's seller information string (may be blank).
          nullable: true
          example: example string
        policy_update_date:
          type: integer
          description: The date and time of the last update to the shop's policies, in epoch seconds.
          minimum: 0
          example: 1
        policy_has_private_receipt_info:
          type: boolean
          description: When true, EU receipts display private info.
          example: true
        has_unstructured_policies:
          type: boolean
          description: When true, the shop displays additional unstructured policy fields.
          example: true
        policy_privacy:
          type: string
          description: The shop's privacy policy string (may be blank).
          nullable: true
          example: example string
        vacation_autoreply:
          type: string
          description: The shop's automatic reply string displayed in new conversations when `is_vacation` is true.
          nullable: true
          example: example string
        url:
          type: string
          description: The URL string for this shop.
          example: https://www.etsy.com/listing/123456789
        image_url_760x100:
          type: string
          description: The URL string for this shop's banner image.
          nullable: true
          example: https://www.etsy.com/listing/123456789
        num_favorers:
          type: integer
          description: The number of users who marked this shop a favorite.
          minimum: 0
          example: 1
        languages:
          type: array
          description: A list of language strings for the shop's enrolled languages where the default shop language is the first element in the array.
          items:
            type: string
        icon_url_fullxfull:
          type: string
          description: The URL string for this shop's icon image.
          nullable: true
          example: https://www.etsy.com/listing/123456789
        is_using_structured_policies:
          type: boolean
          description: When true, the shop accepted using structured policies.
          example: true
        has_onboarded_structured_policies:
          type: boolean
          description: When true, the shop accepted OR declined after viewing structured policies onboarding.
          example: true
        include_dispute_form_link:
          type: boolean
          description: When true, this shop's policies include a link to an EU online dispute form.
          example: true
        is_direct_checkout_onboarded:
          type: boolean
          description: '(**DEPRECATED: Replaced by _is_etsy_payments_onboarded_.) When true, the shop has onboarded onto Etsy Payments.'
          example: true
        is_etsy_payments_onboarded:
          type: boolean
          description: When true, the shop has onboarded onto Etsy Payments.
          example: true
        is_calculated_eligible:
          type: boolean
          description: When true, the shop is eligible for calculated shipping profiles. (Only available in the US and Canada)
          example: true
        is_opted_in_to_buyer_promise:
          type: boolean
          description: When true, the shop opted in to buyer promise.
          example: true
        is_shop_us_based:
          type: boolean
          description: When true, the shop is based in the US.
          example: true
        transaction_sold_count:
          type: integer
          description: The total number of sales ([transactions](/documentation/reference#tag/Shop-Receipt-Transactions)) for this shop.
          minimum: 0
          example: 1
        shipping_from_country_iso:
          type: string
          description: The country ISO the shop is shipping from.
          format: ISO 3166-1 alpha-2
          nullable: true
          example: US
        shop_location_country_iso:
          type: string
          description: The country ISO where the shop is located.
          format: ISO 3166-1 alpha-2
          nullable: true
          example: US
        review_count:
          type: integer
          description: Number of reviews of shop listings in the past year.
          nullable: true
          example: 1
        review_average:
          type: number
          description: Average rating based on reviews of shop listings in the past year.
          format: float
          nullable: true
          example: 1.0
    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'
    User:
      type: object
      x-resource-id: User
      description: Represents a single user of the site
      properties:
        user_id:
          type: integer
          description: The numeric ID of a user. This number is also a valid shop ID for the user's shop.
          format: int64
          minimum: 1
          example: 456789
        primary_email:
          type: string
          description: An email address string for the user's primary email address. Access to this field is granted on a case by case basis for third-party integrations that require full access
          format: email
          nullable: true
          example: seller@example.com
        first_name:
          type: string
          description: The user's first name.
          nullable: true
          example: Handmade Ceramic Mug
        last_name:
          type: string
          description: The user's last name.
          nullable: true
          example: Handmade Ceramic Mug
        image_url_75x75:
          type: string
          description: The user's avatar URL.
          nullable: true
          example: https://www.etsy.com/listing/123456789
    Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion:
      type: object
      x-resource-id: Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion
      properties:
        question_id:
          type: integer
          format: int64
          nullable: true
          minimum: 1
          example: 1
        question_text:
          type: string
          example: example string
        instructions:
          type: string
          nullable: true
          example: example string
        question_type:
          type: string
          example: example string
        required:
          type: boolean
          example: true
        max_allowed_characters:
          type: integer
          nullable: true
          example: 1
        max_allowed_files:
          type: integer
          nullable: true
          example: 1
        options:
          type: array
          nullable: true
          items:
            type: object
            properties:
              option_id:
                type: integer
                format: int64
                nullable: true
                minimum: 1
                example: 1
              label:
                type: string
                example: example string
            required:
            - option_id
            - label
    ShopProductionPartner:
      type: object
      x-resource-id: ShopProductionPartner
      description: Represents a description of a shop production partner.
      properties:
        production_partner_id:
          type: integer
          description: The numeric ID of a production partner.
          format: int64
          minimum: 1
          example: 1
        partner_name:
          type: string
          description: The name or title of the production partner.
          example: Handmade Ceramic Mug
        location:
          type: string
          description: A string representing the production partner location.
          example: example string
    ListingBuyerPrice:
      type: object
      x-resource-id: ListingBuyerPrice
      description: The buyer-facing price for a listing, including VAT, inclusive shipping (UK), and active promotions.
      properties:
        base_price:
          description: The pre-discount listing price with VAT applied, excluding shipping. When a promotion is active, this is the price before the discount is applied.
          oneOf:
          - $ref: '#/components/schemas/Money'
          example: example
        shipping_cost:
          description: The shipping cost to the buyer's country. Includes VAT where applicable. Null when shipping is free or unavailable — use is_free_shipping to distinguish.
          oneOf:
          - $ref: '#/components/schemas/Money'
          nullable: true
          example: example
        is_free_shipping:
          type: boolean
          description: Whether shipping is free to the buyer's country.
          example: true
        original_price:
          description: The display price. For UK buyers, includes base + shipping (DMCC). For others, base price only.
          oneOf:
          - $ref: '#/components/schemas/Money'
          example: example
        discounted_price:
          description: The sale price. For UK buyers, includes base + shipping. For others, base price only. Null if no active promotion.
          oneOf:
          - $ref: '#/components/schemas/Money'
          nullable: true
          example: example
        discount_amount:
          description: The discount amount as money (original_price - discounted_price). Null if no active promotion.
          oneOf:
          - $ref: '#/components/schemas/Money'
          nullable: true
          example: example
        discount_percentage:
          type: integer
          description: The discount percentage (e.g. 20 for 20% off). Null if no active promotion or if the promotion is a fixed-amount discount.
          nullable: true
          example: 1
        has_discount:
          type: boolean
          description: Whether an active promotion applies to this listing.
          example: true
        discount_start_epoch:
          type: integer
          description: The start timestamp of the active promotion. Null if no active promotion.
          nullable: true
          example: 1758153645
        discount_end_epoch:
          type: integer
          description: The end timestamp of the active promotion. Null if no active promotion.
          nullable: true
          example: 1758153645
    ListingInventoryProductOffering:
      type: object
      x-resource-id: ListingInventoryProductOffering
      description: A representation of an offering for a listing.
      properties:
        offering_id:
          type: integer
          description: The ID for the ProductOffering
          format: int64
          minimum: 1
          example: 1
        quantity:
          type: integer
          description: The quantity the ProductOffering
          minimum: 0
          example: 1
        is_enabled:
          type: boolean
          description: Whether or not the offering can be shown to buyers.
          example: true
        is_deleted:
          type: boolean
          description: Whether or not the offering has been deleted.
          example: true
        price:
          description: Price data for this ProductOffering
          oneOf:
          - $ref: '#/components/schemas/Money'
          example: example
        readiness_state_id:
          type: integer
          description: Processing Profile for this ProductOffering
          format: int64
          nullable: true
          minimum: 1
          example: 1
    ShopListingsWithAssociations:
      type: object
      x-resource-id: ShopListingsWithAssociations
      description: A set of ShopListing resources with associations.
      properties:
        count:
          type: integer
          description: The number of ShopListing resources found.
          minimum: 0
          example: 1
        results:
          type: array
          description: The ShopListing resources found.
          items:
            description: The ShopListing resources found.
            oneOf:
            - $ref: '#/components/schemas/ShopListingWithAssociations'
    ListingTranslations:
      type: object
      x-resource-id: ListingTranslations
      description: Container for all current supported translations of a listing. Note that Etsy periodically adds/removes languages, so this list may change in the future.
      properties:
        de:
          oneOf:
          - $ref: '#/components/schemas/ListingTranslation'
          nullable: true
          example: example
        en-GB:
          oneOf:
          - $ref: '#/components/schemas/ListingTranslation'
          nullable: true
          example: example
        en-IN:
          oneOf:
          - $ref: '#/components/schemas/ListingTranslation'
          nullable: true
          example: example
        en-US:
          oneOf:
          - $ref: '#/components/schemas/ListingTranslation'
          nullable: true
          example: example
        es:
          oneOf:
          - $ref: '#/components/schemas/ListingTranslation'
          nullable: true
          example: example
        fr:
          oneOf:
          - $ref: '#/components/schemas/ListingTranslation'
          nullable: true
          example: example
        it:
          oneOf:
          - $ref: '#/components/schemas/ListingTranslation'
          nullable: true
          example: example
        ja:
          oneOf:
          - $ref: '#/components/schemas/ListingTranslation'
          nullable: true
          example: example
        nl:
          oneOf:
          - $ref: '#/components/schemas/ListingTranslation'
          nullable: true
          example: example
        pl:
          oneOf:
          - $ref: '#/components/schemas/ListingTranslation'
          nullable: true
          example: example
        pt:
          oneOf:
          - $ref: '#/components/schemas/ListingTranslation'
          nullable: true
          example: example
        ru:
          oneOf:
          - $ref: '#/components/schemas/ListingTranslation'
          nullable: true
          example: example
        sv:
          oneOf:
          - $ref: '#/components/schemas/ListingTranslation'
          nullable: true
          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
          description: The date and time of the last state change of this listing.
          nullable: true
          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
          description: The numeric ID of a section in a specific Etsy shop.
          format: int64
          nullable: true
          minimum: 1
          example: 1
        featured_rank:
          type: integer
          description: 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.
          example: 1
        url:
          type: string
          description: The full URL to the listing's page on Etsy.
          example: https://www.etsy.com/listing/123456789
        num_favorers:
          type: integer
          description: The number of users who marked this Listing a favorite.
          minimum: 0
          example: 1
        non_taxable:
          type: boolean
          description: When true, applicable [shop](/documentation/reference#tag/Shop) tax rates do not apply to this listing at checkout.
          example: true
        is_taxable:
          type: boolean
          description: When true, applicable [shop](/documentation/reference#tag/Shop) tax rates apply to this listing at checkout.
          example: true
        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.
          example: true
        is_personalizable:
          type: boolean
          description: When true, this listing is personalizable. The default value is false.
          example: true
        listing_type:
          type: string
          description: An enumerated type string that indicates whether the listing is physical or a digital download.
          enum:
          - physical
          - download
          - both
          example: physical
        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.'
          items:
            type: string
        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.'
          items:
            type: string
        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
          example: 1
        return_policy_id:
          type: integer
          description: The numeric ID of the [Return Policy](/documentation/reference#operation/getShopReturnPolicies).
          format: int64
          nullable: true
          minimum: 1
          example: 1
        processing_min:
          type: integer
          description: The minimum number of days required to process this listing. Default value is null.
          nullable: true
          minimum: 0
          example: 1
        processing_max:
          type: integer
          description: The maximum number of days required to process this listing. Default value is null.
          nullable: true
          minimum: 0
          example: 1
        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'.
          nullable: true
          enum:
          - i_did
          - someone_else
          - collective
          example: i_did
        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'.
          nullable: true
          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
          example: made_to_order
        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'.
          nullable: true
          example: true
        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
          example: 0.5
        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
          example: oz
        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
          example: 1.0
        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
          example: 1.0
        item_height:
          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
          example: 1.0
        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
          example: in
        is_private:
          type: boolean
          description: When true, this is a private listing intended for a specific buyer and hidden from shop view.
          example: true
        style:
          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.'
          items:
            type: string
        file_data:
          type: string
          description: A string describing the files attached to a digital listing.
          nullable: true
          example: example string
        has_variations:
          type: boolean
          description: When true, the listing has variations.
          example: true
        should_auto_renew:
          type: boolean
          description: When true, renews a listing for four months upon expiration.
          example: true
        language:
          type: string
          description: 'The IETF language tag for the default language of the listing. Ex: `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`, `ru`.'
          nullable: true
          example: en-US
        price:
          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.'
          oneOf:
          - $ref: '#/components/schemas/Money'
          example: example
        converted_price:
          description: The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.
          oneOf:
          - $ref: '#/components/schemas/Money'
          nullable: true
          example: example
        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.
          nullable: true
          example: 1234
        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
          example: 1
        suggested_title:
          type: string
          description: A title string suggested by Etsy. Only available for a user's own listings, when allow_suggested_title param is present, and when a shop's language setting is English. Not all listings will have suggestions.
          nullable: true
          example: Handmade Ceramic Mug — Stoneware
    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
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header
      description: Every request to a v3 API endpoint must include this data in the format `keystring:shared_secret`. Your keystring and shared secret are available on the [Your Apps](https://www.etsy.com/developers/your-apps) page.
    oauth2:
      type: oauth2
      description: Open API v3 supports authenticating via OAuth 2.0. More information about Etsy's specific implementation of OAuth2 can be found [here](/documentation/essentials/oauth2).
      flows:
        authorizationCode:
          authorizationUrl: https://www.etsy.com/oauth/connect
          tokenUrl: https://openapi.etsy.com/v3/public/oauth/token
          scopes:
            address_r: see billing and shipping addresses
            address_w: update billing and shipping addresses
            billing_r: see all billing statement data
            cart_r: read shopping carts
            cart_w: add/remove from shopping carts
            email_r: read a user profile
            favorites_r: see private favorites
            favorites_w: add/remove favorites
            feedback_r: see purchase info in feedback
            listings_d: delete listings
            listings_r: see all listings (including expired etc)
            listings_w: create/edit listings
            profile_r: see all profile data
            profile_w: update user profile, avatar, etc
            recommend_r: see recommended listings
            recommend_w: accept/reject recommended listings
            shops_r: see private shop info
            shops_w: update shop
            transactions_r: see all checkout/payment data
            transactions_w: update receipts
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