Etsy BuyerTaxonomy API

openapi: 3.0.2
info:
  title: Etsy Open API v3 BuyerTaxonomy 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: BuyerTaxonomy
paths:
  /v3/application/buyer-taxonomy/nodes:
    get:
      operationId: getBuyerTaxonomyNodes
      description: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>


        Retrieves the full hierarchy tree of buyer taxonomy nodes.'
      tags:
      - BuyerTaxonomy
      parameters: []
      responses:
        '200':
          description: List the full hierarchy tree of buyer taxonomy nodes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerTaxonomyNodes'
              examples:
                GetBuyerTaxonomyNodes200Example:
                  summary: Default getBuyerTaxonomyNodes 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    results:
                    - null
        '500':
          description: The server encountered an internal error. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetBuyerTaxonomyNodes500Example:
                  summary: Default getBuyerTaxonomyNodes 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Buyer Taxonomy Nodes
  /v3/application/buyer-taxonomy/nodes/{taxonomy_id}/properties:
    get:
      operationId: getPropertiesByBuyerTaxonomyId
      description: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>


        Retrieves a list of product properties, with applicable scales and values, supported for a specific buyer taxonomy ID.'
      tags:
      - BuyerTaxonomy
      parameters:
      - name: taxonomy_id
        in: path
        description: 'The unique numeric ID of an Etsy taxonomy node, which is a metadata category for listings organized into the seller taxonomy hierarchy tree. For example, the "shoes" taxonomy node (ID: 1429, level: 1) is higher in the hierarchy than "girls'' shoes" (ID: 1440, level: 2). The taxonomy nodes assigned to a listing support access to specific standardized product scales and properties. For example, listings assigned the taxonomy nodes "shoes" or "girls'' shoes" support access to the "EU" shoe size scale with its associated property names and IDs for EU shoe sizes, such as property `value_id`:"1394", and `name`:"38".'
        required: true
        schema:
          type: integer
          description: 'The unique numeric ID of an Etsy taxonomy node, which is a metadata category for listings organized into the seller taxonomy hierarchy tree. For example, the "shoes" taxonomy node (ID: 1429, level: 1) is higher in the hierarchy than "girls'' shoes" (ID: 1440, level: 2). The taxonomy nodes assigned to a listing support access to specific standardized product scales and properties. For example, listings assigned the taxonomy nodes "shoes" or "girls'' shoes" support access to the "EU" shoe size scale with its associated property names and IDs for EU shoe sizes, such as property `value_id`:"1394", and `name`:"38".'
          format: int64
          minimum: 1
        example: 1234
      responses:
        '200':
          description: A list of product properties, with applicable scales and values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerTaxonomyNodeProperties'
              examples:
                GetPropertiesByBuyerTaxonomyId200Example:
                  summary: Default getPropertiesByBuyerTaxonomyId 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    results:
                    - null
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetPropertiesByBuyerTaxonomyId404Example:
                  summary: Default getPropertiesByBuyerTaxonomyId 404 response
                  x-microcks-default: true
                  value:
                    error: example string
        '400':
          description: There was a problem with the request data. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetPropertiesByBuyerTaxonomyId400Example:
                  summary: Default getPropertiesByBuyerTaxonomyId 400 response
                  x-microcks-default: true
                  value:
                    error: example string
        '500':
          description: The server encountered an internal error. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetPropertiesByBuyerTaxonomyId500Example:
                  summary: Default getPropertiesByBuyerTaxonomyId 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Properties by Buyer Taxonomy Id
components:
  schemas:
    ErrorSchema:
      type: object
      x-resource-id: ErrorSchema
      required:
      - error
      properties:
        error:
          type: string
          example: example string
    BuyerTaxonomyNode:
      type: object
      x-resource-id: BuyerTaxonomyNode
      description: A taxonomy node in the buyer taxonomy tree.
      properties:
        id:
          type: integer
          description: 'The unique numeric ID of an Etsy taxonomy node, which is a metadata category for listings organized into the seller taxonomy hierarchy tree. For example, the "shoes" taxonomy node (ID: 1429, level: 1) is higher in the hierarchy than "girls'' shoes" (ID: 1440, level: 2). The taxonomy nodes assigned to a listing support access to specific standardized product scales and properties. For example, listings assigned the taxonomy nodes "shoes" or "girls'' shoes" support access to the "EU" shoe size scale with its associated property names and IDs for EU shoe sizes, such as property `value_id`:"1394", and `name`:"38".'
          format: int64
          minimum: 1
          example: 1
        level:
          type: integer
          description: The integer depth of this taxonomy node in the seller taxonomy tree, with roots at level 0.
          minimum: 0
          example: 1
        name:
          type: string
          description: The name string for this taxonomy node.
          example: Handmade Ceramic Mug
        parent_id:
          type: integer
          description: The numeric taxonomy ID of the parent of this node.
          format: int64
          nullable: true
          minimum: 1
          default: null
          example: 1
        children:
          type: array
          description: An array of taxonomy nodes for all the direct children of this taxonomy node in the seller taxonomy tree.
          items:
            description: An array of taxonomy nodes for all the direct children of this taxonomy node in the seller taxonomy tree.
            oneOf:
            - $ref: '#/components/schemas/BuyerTaxonomyNode'
        full_path_taxonomy_ids:
          type: array
          description: An array of `taxonomy_id`s including this node and all of its direct parents in the seller taxonomy tree up to a root node. They are listed in order from root to leaf.
          items:
            type: integer
            format: int64
            minimum: 1
    BuyerTaxonomyNodes:
      type: object
      x-resource-id: BuyerTaxonomyNodes
      description: A list of taxonomy nodes from the buyer taxonomy tree.
      properties:
        count:
          type: integer
          description: The number of results.
          minimum: 0
          example: 1
        results:
          type: array
          description: The list of requested resources.
          items:
            description: The list of requested resources.
            oneOf:
            - $ref: '#/components/schemas/BuyerTaxonomyNode'
    BuyerTaxonomyNodeProperty:
      type: object
      x-resource-id: BuyerTaxonomyNodeProperty
      description: A product property definition.
      properties:
        property_id:
          type: integer
          description: The unique numeric ID of this product property.
          format: int64
          minimum: 1
          example: 1
        name:
          type: string
          description: The name string for this taxonomy node.
          example: Handmade Ceramic Mug
        display_name:
          type: string
          description: The human-readable product property name string.
          example: Handmade Ceramic Mug
        scales:
          type: array
          description: A list of available scales.
          items:
            description: A list of available scales.
            oneOf:
            - $ref: '#/components/schemas/BuyerTaxonomyPropertyScale'
        is_required:
          type: boolean
          description: When true, listings assigned eligible taxonomy IDs require this property.
          example: true
        supports_attributes:
          type: boolean
          description: When true, you can use this property in listing properties.
          example: true
        supports_variations:
          type: boolean
          description: When true, you can use this property in listing inventory.
          example: true
        is_multivalued:
          type: boolean
          description: When true, you can assign multiple property values to this property
          example: true
        max_values_allowed:
          type: integer
          description: When true, you can assign multiple property values to this property
          nullable: true
          example: 1
        possible_values:
          type: array
          description: A list of supported property value strings for this property.
          items:
            description: A list of supported property value strings for this property.
            oneOf:
            - $ref: '#/components/schemas/BuyerTaxonomyPropertyValue'
        selected_values:
          type: array
          description: A list of property value strings automatically and always selected for the given property.
          items:
            description: A list of property value strings automatically and always selected for the given property.
            oneOf:
            - $ref: '#/components/schemas/BuyerTaxonomyPropertyValue'
    BuyerTaxonomyPropertyScale:
      type: object
      x-resource-id: BuyerTaxonomyPropertyScale
      description: A scale defining the assignable increments for the property values available to specific product properties.
      properties:
        scale_id:
          type: integer
          description: The unique numeric ID of a scale.
          format: int64
          minimum: 1
          example: 1
        display_name:
          type: string
          description: The name string for a scale.
          example: Handmade Ceramic Mug
        description:
          type: string
          description: The description string for a scale.
          example: Beautifully crafted handmade ceramic mug, kiln-fired in our Brooklyn studio.
    BuyerTaxonomyNodeProperties:
      type: object
      x-resource-id: BuyerTaxonomyNodeProperties
      description: A list of product property definitions.
      properties:
        count:
          type: integer
          description: The number of results.
          minimum: 0
          example: 1
        results:
          type: array
          description: The list of requested resources.
          items:
            description: The list of requested resources.
            oneOf:
            - $ref: '#/components/schemas/BuyerTaxonomyNodeProperty'
    BuyerTaxonomyPropertyValue:
      type: object
      x-resource-id: BuyerTaxonomyPropertyValue
      description: A property value for a specific product property, which may also employ a specific scale.
      properties:
        value_id:
          type: integer
          description: The numeric ID of this property value.
          format: int64
          nullable: true
          minimum: 1
          example: 1
        name:
          type: string
          description: The name string of this property value.
          example: Handmade Ceramic Mug
        scale_id:
          type: integer
          description: The numeric scale ID of the scale to which this property value belongs.
          format: int64
          nullable: true
          minimum: 1
          example: 1
        equal_to:
          type: array
          description: A list of numeric property value IDs this property value is equal to (if any).
          items:
            type: integer
            minimum: 0
  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