Every item that a seller wants to sell on eBay must be assigned to a category under which the item will be listed. Assigning a listing to an appropriate category helps to ensure that potential buyers can find that listing by browsing or searching within that category. Assigning a listing to the wrong category can severely restrict the seller's ability to sell that item. Before creating a listing for an item, you can use the Taxonomy API to assist the seller to discover the category that's appropriate for the item, and the required and optional descriptive aspects of that category.
Categories are organized into a tree hierarchy. Approximately 20 eBay marketplaces each use a default category tree, which is typically structured differently for each marketplace. The category tree structure is also subject to change as categories are added, expanded, consolidated, or removed (users are notified of any changes).
Note: Currently, for each eBay marketplace the default category tree is the only category tree available. This will change in the future as new category trees are developed for more specialized uses.
Following is an example of the Taxonomy API work flow for discovering the category that best applies to a particular item in a particular eBay marketplace. If a seller wants to sell an item related to the iPhone, you can discover the most appropriate leaf categories that apply to the iPhone. Use the Taxonomy API to accomplish this.
For more information about working with categories, see the Taxonomy API.
Identify the default category tree for a marketplace
Use the getDefaultCategoryTreeId call to identify the default category tree for your marketplace; for example:
GET https://api.ebay.com/commerce/taxonomy/v1_beta/get_default_category_tree_id?marketplace_id=EBAY_US
The response payload contains the category tree ID and version:
{
"categoryTreeId": "0",
"categoryTreeVersion": "117"
}
You use the value of categoryTreeId to identify that tree in subsequent Taxonomy API calls.
Retrieve suggested categories
You can apply eBay's functionality to recommend categories for your sellers to use to list their items. Use the getCategorySuggestions call to retrieve an array of category tree leaf nodes in the specified category tree that are considered by eBay to most closely correspond to the query string provided:
GET https://api.ebay.com/commerce/taxonomy/v1_beta/category_tree/0/get_category_suggestions?q=iphone
The response payload contains several leaf category nodes (shown in bold), along with their ancestor nodes extending up to the tree's root. Note that more categories were returned, but some have been removed for readability:
{
"categorySuggestions": [
{
"category": {
"categoryId": "9355",
"categoryName": "Cell Phones & Smartphones"
},
"categoryTreeNodeLevel": 2,
"categoryTreeNodeAncestors": [
{
"categoryId": "15032",
"categoryName": "Cell Phones & Accessories",
"categoryTreeNodeLevel": 1,
"categorySubtreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
category_tree/0/get_category_subtree?category_id=15032"
}
]
},
...
{
"category": {
"categoryId": "20349",
"categoryName": "Cases, Covers & Skins"
},
"categoryTreeNodeLevel": 3,
"categoryTreeNodeAncestors": [
{
"categoryId": "9394",
"categoryName": "Cell Phone Accessories",
"categoryTreeNodeLevel": 2,
"categorySubtreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
category_tree/0/get_category_subtree?category_id=9394"
},
{
"categoryId": "15032",
"categoryName": "Cell Phones & Accessories",
"categoryTreeNodeLevel": 1,
"categorySubtreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta
/category_tree/0/get_category_subtree?category_id=15032"
}
]
},
...
{
"category": {
"categoryId": "58543",
"categoryName": "Accessory Bundles"
},
"categoryTreeNodeLevel": 3,
"categoryTreeNodeAncestors": [
{
"categoryId": "9394",
"categoryName": "Cell Phone Accessories",
"categoryTreeNodeLevel": 2,
"categorySubtreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
category_tree/0/get_category_subtree?category_id=9394"
},
{
"categoryId": "15032",
"categoryName": "Cell Phones & Accessories",
"categoryTreeNodeLevel": 1,
"categorySubtreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
category_tree/0/get_category_subtree?category_id=15032"
}
]
},
{
"category": {
"categoryId": "45071",
"categoryName": "Cell Phones"
},
"categoryTreeNodeLevel": 3,
"categoryTreeNodeAncestors": [
{
"categoryId": "45065",
"categoryName": "Wholesale Lots",
"categoryTreeNodeLevel": 2,
"categorySubtreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
category_tree/0/get_category_subtree?category_id=45065"
},
{
"categoryId": "15032",
"categoryName": "Cell Phones & Accessories",
"categoryTreeNodeLevel": 1,
"categorySubtreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
category_tree/0/get_category_subtree?category_id=15032"
}
]
}
],
"categoryTreeId": "0",
"categoryTreeVersion": "117"
}
You can present these categories to your seller, so the seller can select a leaf category for the listing. For more information about working with categories, see the Taxonomy API.
Identify the descriptive aspects of a category
Once you determine which leaf category to use for listing an item, you must identify the aspects that are associated with that category. An aspect is a predefined attribute associated with a leaf category, such as color or size. Sellers must provide or select values for some aspects of a given category when listing items in that category. Use the Taxonomy API's getItemAspectsForCategory call to discover which aspects are required, which are optional, and how their values must be formatted and constrained. The following example uses category 67726 = Diamond Rings:
GET https://api.ebay.com/commerce/taxonomy/v1_beta/category_tree/{category_tree_id}/get_item_aspects_for_category?category_id=67726
Following is a snippet of the response from this call:
{
"aspects": [
...
{
"localizedAspectName":"Metal Purity",
"aspectConstraint": {
"aspectDataType":"STRING",
"itemToAspectCardinality":"SINGLE",
"aspectMode":"SELECTION_ONLY",
"aspectRequired":false,
"aspectEnabledForVariations":false
},
"aspectValues": [
{
"localizedValue": "9k",
"valueConstraints": [
{
"applicableForLocalizedAspectName": "Metal",
"applicableForLocalizedAspectValues": [
"Multi-Tone Gold",
"White Gold",
"Yellow Gold",
"Rose Gold"
]
}
]
},
{
"localizedValue": "10k",
"valueConstraints": [
{
"applicableForLocalizedAspectName": "Metal",
"applicableForLocalizedAspectValues": [
"Multi-Tone Gold",
"White Gold",
"Yellow Gold",
"Rose Gold"
]
}
]
},
...
]
},
...
]
}
In this example, the aspect with the localized name of Metal Purity is optional for inclusion in a listing in the Diamond Ring category. Its localized values of 9k and 10k can be selected by the seller, but not for all diamond rings. Both values are constrained; they can be specified only for certain values of another aspect. The metal purity values of 9k and 10k can be applied to the listing only if the other aspect (with the localized name of Metal) has one of the four localized aspect values shown here.
In other words, you can list a diamond ring with a 9k or 10k metal purity only if the ring is made of one of four types of gold. The Metal aspect constrains the use of the Metal Purity aspect.
After you retrieve the aspects of the specified category, you can present the required and optional aspects and their available values to the seller using the aspect and value constraints to validate the seller's choices. Once the seller selects the aspect values, use the Inventory API's createOrReplaceInventoryItem call to provide these aspect values in the product.aspects container.
Retrieve the complete category tree
You can maintain your own copy of the default category tree, and enable sellers to browse or search the tree hierarchy and select the appropriate category. Use the getCategoryTree call to retrieve the entire category tree:
GET https://api.ebay.com/commerce/taxonomy/v1_beta/category_tree/0
This call can return a very large payload (tens of thousands of categories), so you are strongly advised to submit the request with the following HTTP header:
Accept-Encoding: gzip
With this header (in addition to the required headers described under HTTP Request Headers), the call returns the response with gzip compression.
The following severely trimmed example provides an idea of the category tree structure:
{
"categoryTreeId": "0",
"categoryTreeVersion": "117",
"rootCategoryNode": {
"category": {
"categoryId": "0",
"categoryName": "Root"
},
"childCategoryTreeNodes": [
{
"category": {
"categoryId": "1",
"categoryName": "Collectibles"
},
"parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
category_tree/0/get_category_subtree?category_id=1",
"childCategoryTreeNodes": [
{
"category": {
"categoryId": "34",
"categoryName": "Advertising"
},
"parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
category_tree/0/get_category_subtree?category_id=34",
"childCategoryTreeNodes": [
{
"category": {
"categoryId": "36",
"categoryName": "Soda"
},
"parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
category_tree/0/get_category_subtree?category_id=36",
"childCategoryTreeNodes": [
{
"category": {
"categoryId": "13600",
"categoryName": "Coca-Cola"
},
"parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta
/category_tree/0/get_category_subtree?category_id=13600",
"childCategoryTreeNodes": [
{
"category": {
"categoryId": "38",
"categoryName": "Other Coca-Cola Ads"
},
"parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
category_tree/0/get_category_subtree?category_id=38",
"categoryTreeNodeLevel": 5,
"leafCategoryTreeNode": true
},
...
],
"categoryTreeNodeLevel": 4
},
...
],
"categoryTreeNodeLevel": 3
},
...
],
"categoryTreeNodeLevel": 2
},
...
],
"categoryTreeNodeLevel": 1
},
...
{
"category": {
"categoryId": "172008",
"categoryName": "Gift Cards & Coupons"
},
"parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1_beta/
category_tree/0/get_category_subtree?category_id=172008",
"childCategoryTreeNodes": [
...
],
"categoryTreeNodeLevel": 1
}
],
"categoryTreeNodeLevel": 0
},
"applicableMarketplaceIds": []
}
With such a large set of categories, you will probably want to present a limited portion of the tree at a time to sellers, and reveal additional child categories when a seller selects one at the current level.
You will not need to retrieve this category tree again, unless eBay publishes a new version. You can determine this by using the getCategoryTree call to retrieve and compare the categoryTreeVersion field to the one you have cached.