taxonomy APIv1_beta.3.0

Taxonomy API release notes

Just getting started with the Taxonomy API? See the following documents for details on using this API:

The API release history

The following table lists the releases for the Taxonomy API:


Release Date

Summary of Release

Version 1_beta.3.0


New methods: getCompatibilityProperties and getCompatibilityPropertyValues

Version 1_beta.2.0


New fields: aspectApplicableTo and aspectMaxLength in getItemAspectsForCategory method

Version 1_beta.1.0


New method: getItemAspectsForCategory

Version 1_beta.0.0


Initial release of Version 1_beta.0.0

Version 1_beta.3.0

API updates

This API release contains the following updates and changes:

New Methods

getCompatibilityProperties : GET /category_tree/{category_tree_id}/get_compatibility_properties

This method retrieves predefined motor vehicle aspects that are associated with a specific leaf category within an eBay marketplace that supports parts and compatibility. Motor vehicle aspects for a US or US Motors category may include 'Year', 'Make', 'Model', 'Trim', and 'Engine'. Compatibility properties can vary by eBay marketplace and category.

getCompatibilityPropertyValues : GET /category_tree/{category_tree_id}/get_compatibility_property_values

This method retrieves compatibility property values that match the specified compatibility property and the filters that are used in URI.

Version 1_beta.2.0

API updates

This API release contains the following updates and changes:

Schema changes

New aspectApplicableTo and aspectMaxLength fields added to getItemAspectsForCategory method

The aspectApplicableTo and aspectMaxLength fields were added to the response payload of the getItemAspectsForCategory method. The aspectApplicableTo field is used to indicate if the aspect (in the localizedAspectName field) is a product aspect (relevant to catalog products in the category) or an item/instance aspect, which is an aspect whose value will vary based on a particular instance of the product. The aspectMaxLength field may be returned for item/instance aspects, and it instructs the seller the maximum number of characters that can be used for the value of the corresponding instance aspect.

In addition to these two fields, the AspectApplicableToEnum type was added to define the closed set of enumeration values that can be returned in the aspectApplicableTo field.

Version 1_beta.1.0

API updates

This API release contains the following updates and changes:

New Call

getItemAspectsForCategory : GET /category_tree/{category_tree_id}/get_item_aspects_for_category

Schema changes

New call to support leaf category aspects

An aspect is a predefined attribute associated with a leaf category, such as color or size. Each leaf category has its own set of aspects. The aspect object contains the aspect name, its valid values, and constraints on the use of those values. Other aspects of the category may be available but not required.

The new getItemAspectsForCategory call returns a list of aspects that are appropriate or necessary for accurately describing items in a specified leaf category. Each aspect identifies an item attribute (for example, color). Sellers must provide or select values for some aspects of a given category when using the Inventory API's createOrReplaceInventoryItem call to define inventory items to offer in that category.

Version 1_beta.0.0

This is the initial release of the Taxonomy API, Version 1_beta.0.0. For a list of the new calls, see the Taxonomy API Reference.


See the API Site Status for announcements regarding recently resolved or current system wide issues. Visit the Developer Support page for support options and information on filing bugs.

Availability of OpenAPI Specification

This release of the Taxonomy API includes Beta version downloadable JSON and YAML formats of the API contract that comply with version 2.0 of the OpenAPI Specification. The OpenAPI Specification is a widely adopted standard for describing RESTful APIs. The eBay API specification files can facilitate your development process through the ability to generate client code in numerous languages, using the Swagger-Codegen tools, as well as the ability to easily view and test the API via the Swagger UI projects. Development of the OpenAPI Specification is overseen by the Open API Initiative, an open source collaborative project of the Linux Foundation.

Note: If you want to use the Swagger editing tool for viewing and testing, we advise that you use the version of the editor that is compatible with 2.0 OpenAPI specifications:

Read the eBay API documentation for comprehensive API details, including allowed values, constraints, method-specific error messages, and implementation details.

File download  Download Taxonomy API JSON specification (beta)

File download  Download Taxonomy API YAML specification (beta)