eBay Taxonomy Technical Scope

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

The purpose of this page is to give detailed explanations of how we will download the taxonomy for eBay.

The taxonomy must be stored in classes, which should be available for exports from the UI in Export Taxonomy table. The taxonomy is used for internal validation and we will need to map the values and push the codes to eBay.

Every time we send products for creation we have to do internal check if all required attributes are part of the product as Item Specifics or Variation Specifics according to their taxonomy which we download and store on the instance.

Please note the taxonomy should be part of eBay_v2 since we will be using the new APIs. Also the taxonomy is per territory and we will have separate taxonomy for each territory.

getDefaultCategoryTreeId

Using this call, we are able to get the category tree id and version which we need in the next step.

API Call:`https://api.ebay.com/commerce/taxonomy/v1/get_default_category_tree_id?marketplace_id={Identifier}`

The marketplace_id is available in our mapping list within the code and also can be found here API Docs: getDefaultCategoryTreeId

Sample Request: GET https://api.ebay.com/commerce/taxonomy/v1/get_default_category_tree_id?marketplace_id=EBAY_GB

Sample Response:

{
    "categoryTreeId": "3",
    "categoryTreeVersion": "122"
}

getCategoryTree

The second step is to get the complete list of categories API Call:`https://api.ebay.com/commerce/taxonomy/v1/category_tree/{categoryTreeId}`

We have to use the categoryTreeId from the previous call API Docs:https://developer.ebay.com/api-docs/commerce/taxonomy/resources/category_tree/methods/getCategoryTree

Sample Request: GET https://api.ebay.com/commerce/taxonomy/v1/category_tree/3

Sample Response:

{
    "categoryTreeId": "3",
    "categoryTreeVersion": "122",
    "rootCategoryNode": {
        "category": {
            "categoryId": "0",
            "categoryName": "Root"
        },
        "childCategoryTreeNodes": [
            {
                "category": {
                    "categoryId": "1",
                    "categoryName": "Collectables"
                },
                "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=0",
                "childCategoryTreeNodes": [
                    {
                        "category": {
                            "categoryId": "34",
                            "categoryName": "Advertising Collectables"
                        },
                        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=1",
                        "childCategoryTreeNodes": [
                            {
                                "category": {
                                    "categoryId": "35",
                                    "categoryName": "Other Advertising Collectables"
                                },
                                "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=34",
                                "categoryTreeNodeLevel": 3,
                                "leafCategoryTreeNode": true
                            },
                            {
                                "category": {
                                    "categoryId": "36",
                                    "categoryName": "Soft Drinks Advertising"
                                },
                                "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=34",
                                "childCategoryTreeNodes": [
                                    {
                                        "category": {
                                            "categoryId": "13600",
                                            "categoryName": "Coca-Cola Advertising"
                                        },
                                        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=36",
                                        "categoryTreeNodeLevel": 4,
                                        "leafCategoryTreeNode": true
                                    },
                                    {
                                        "category": {
                                            "categoryId": "13613",
                                            "categoryName": "Pepsi Advertising"
                                        },
                                        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=36",
                                        "categoryTreeNodeLevel": 4,
                                        "leafCategoryTreeNode": true
                                    },
                                    {
                                        "category": {
                                            "categoryId": "35692",
                                            "categoryName": "Soft Drinks"
                                        },
                                        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=36",
                                        "categoryTreeNodeLevel": 4,
                                        "leafCategoryTreeNode": true
                                    },
                                    {
                                        "category": {
                                            "categoryId": "90645",
                                            "categoryName": "Cocoa Advertising"
                                        },
                                        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=36",
                                        "categoryTreeNodeLevel": 4,
                                        "leafCategoryTreeNode": true
                                    },
                                    {
                                        "category": {
                                            "categoryId": "90646",
                                            "categoryName": "Coffee Advertising"
                                        },
                                        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=36",
                                        "categoryTreeNodeLevel": 4,
                                        "leafCategoryTreeNode": true
                                    },
                                    {
                                        "category": {
                                            "categoryId": "90649",
                                            "categoryName": "Tea Advertising"
                                        },
                                        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=36",
                                        "categoryTreeNodeLevel": 4,
                                        "leafCategoryTreeNode": true
                                    },
                                    {
                                        "category": {
                                            "categoryId": "165265",
                                            "categoryName": "Other Soft Drinks Advertising"
                                        },
                                        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=36",
                                        "categoryTreeNodeLevel": 4,
                                        "leafCategoryTreeNode": true
                                    }
                                ],
                                "categoryTreeNodeLevel": 3
                            },
                            {
                                "category": {
                                    "categoryId": "804",
                                    "categoryName": "Advertising Signs"
                                },
                                "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=34",
                                "categoryTreeNodeLevel": 3,
                                "leafCategoryTreeNode": true
                            },
                            {
                                "category": {
                                    "categoryId": "821",
                                    "categoryName": "Spirits/Distillery Advertising"
                                },
                                "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=34",
                                "categoryTreeNodeLevel": 3,
                                "leafCategoryTreeNode": true
                            },
                            {
                                "category": {
                                    "categoryId": "1313",
                                    "categoryName": "Transportation Advertising"
                                },
                                "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=34",
                                "childCategoryTreeNodes": [
                                    {
                                        "category": {
                                            "categoryId": "27371",
                                            "categoryName": "Automobilia Advertising"
                                        },
                                        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=1313",
                                        "categoryTreeNodeLevel": 4,
                                        "leafCategoryTreeNode": true
                                    },
                                    {
                                        "category": {
                                            "categoryId": "69513",
                                            "categoryName": "Aeronautica"
                                        },
                                        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=1313",
                                        "categoryTreeNodeLevel": 4,
                                        "leafCategoryTreeNode": true
                                    },
                                    {
                                        "category": {
                                            "categoryId": "69514",
                                            "categoryName": "Petrol/Oil Advertising"
                                        },
                                        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=1313",
                                        "categoryTreeNodeLevel": 4,
                                        "leafCategoryTreeNode": true
                                    },
                                    {
                                        "category": {
                                            "categoryId": "69515",
                                            "categoryName": "Other Transport Advertising"
                                        },
                                        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=1313",
                                        "categoryTreeNodeLevel": 4,
                                        "leafCategoryTreeNode": true
                                    },
                                    {
                                        "category": {
                                            "categoryId": "90648",
                                            "categoryName": "Railway Advertising"
                                        },
                                        "parentCategoryTreeNodeHref": "https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_category_subtree?category_id=1313",
                                        "categoryTreeNodeLevel": 4,
                                        "leafCategoryTreeNode": true
                                    }
                                ],
                                "categoryTreeNodeLevel": 3
                            }

Full response added as attachment

3.json

We have a simple tree structure where we have different category tree levels. We are able to list products only in leaf categories. We have the categoryId and the categoryName however in Hemi we want to store the category navigation path and push the id to eBay. At the moment we are storing directly the id in Hemi and we are not validating anything.

First we would like to start using the navigation path from where we will obtain the category id and make additional validation if that category is leaf one otherwise we want to return an error. Using the parentCategoryTreeNodeHref we will be able to track the whole category navigation path.

getItemAspectsForCategory

The third step is to get the complete list of attributes API Call: `https://api.ebay.com/commerce/taxonomy/category_tree/{category_tree_id}/get_item_aspects_for_category?category_id={category_id}`

The category_tree_id is obtained from the first step and we should use the categoryTreeId while the category_id is obtained from the second step and we can call each leaf category_id and obtain its attributes. API Docs:https://developer.ebay.com/api-docs/commerce/taxonomy/resources/category_tree/methods/getItemAspectsForCategory

Sample Request: GET https://api.ebay.com/commerce/taxonomy/v1/category_tree/3/get_item_aspects_for_category?category_id=36431

Sample Response:

{
"aspects":[
{
"localizedAspectName": "Brand",
"aspectConstraint":{
"aspectDataType": "STRING",
"itemToAspectCardinality": "SINGLE",
"aspectMode": "FREE_TEXT",
"aspectRequired": true,
"aspectUsage": "RECOMMENDED",
"aspectEnabledForVariations": false,
"aspectApplicableTo":["PRODUCT"]
},
"aspectValues":[{"localizedValue": "Unbranded" }, {"localizedValue": "(MALIN+GOETZ)" }, {"localizedValue": "+ONE"…]
},
{
"localizedAspectName": "Type",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "SINGLE", "aspectMode": "FREE_TEXT", "aspectRequired": true,…},
"aspectValues":[{"localizedValue": "Antibiotic Cream" }, {"localizedValue": "Antifungal Foot Cream" },…]
},
{
"localizedAspectName": "Body Area",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "MULTI", "aspectMode": "FREE_TEXT", "aspectRequired": false,…},
"aspectValues":[
{"localizedValue": "Feet"},
{"localizedValue": "Leg"}
]
},
{
"localizedAspectName": "Active Ingredients",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "MULTI", "aspectMode": "FREE_TEXT", "aspectRequired": false,…},
"aspectValues":[{"localizedValue": "24K Gold" }, {"localizedValue": "Acetaminophen" }, {"localizedValue": "Alcohol"…]
},
{
"localizedAspectName": "Ingredients",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "MULTI", "aspectMode": "FREE_TEXT", "aspectRequired": false,…},
"aspectValues":[{"localizedValue": "24K Gold" }, {"localizedValue": "Almond Oil" }, {"localizedValue": "Aloe Vera"…]
},
{
"localizedAspectName": "Main Purpose",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "MULTI", "aspectMode": "FREE_TEXT", "aspectRequired": false,…},
"aspectValues":[{"localizedValue": "Antibiotic" }, {"localizedValue": "Antifungal" }, {"localizedValue": "Antiseptic"…]
},
{
"localizedAspectName": "Volume",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "SINGLE", "aspectMode": "FREE_TEXT", "aspectRequired": false,…},
"aspectValues":[{"localizedValue": "5 ml" }, {"localizedValue": "10 ml" }, {"localizedValue": "15 ml"…]
},
{
"localizedAspectName": "Colour",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "SINGLE", "aspectMode": "FREE_TEXT", "aspectRequired": false,…},
"aspectValues":[{"localizedValue": "Beige" }, {"localizedValue": "Black" }, {"localizedValue": "Blue"…]
},
{
"localizedAspectName": "Features",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "MULTI", "aspectMode": "FREE_TEXT", "aspectRequired": false,…},
"aspectValues":[{"localizedValue": "Alcohol-Free" }, {"localizedValue": "All Natural Ingredients" },…]
},
{
"localizedAspectName": "Size",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "SINGLE", "aspectMode": "FREE_TEXT", "aspectRequired": false,…},
"aspectValues":[{"localizedValue": "Jumbo/Family Pack" }, {"localizedValue": "Mini" }, {"localizedValue": "Professional Size"…]
},
{
"localizedAspectName": "MPN",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "MULTI", "aspectMode": "FREE_TEXT", "aspectRequired": false,…}
},
{
"localizedAspectName": "Period After Opening (PAO)",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "SINGLE", "aspectMode": "FREE_TEXT", "aspectRequired": false,…},
"aspectValues":[{"localizedValue": "3M" }, {"localizedValue": "6M" }, {"localizedValue": "9M"…]
},
{
"localizedAspectName": "Product Line",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "SINGLE", "aspectMode": "FREE_TEXT", "aspectRequired": false,…}
},
{
"localizedAspectName": "Formulation",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "MULTI", "aspectMode": "FREE_TEXT", "aspectRequired": false,…},
"aspectValues":[{"localizedValue": "Balm" }, {"localizedValue": "Cream" }, {"localizedValue": "Foam"…]
},
{
"localizedAspectName": "Dosage",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "SINGLE", "aspectMode": "FREE_TEXT", "aspectRequired": false,…},
"aspectValues":[{"localizedValue": "0,09%" }, {"localizedValue": "1%" }, {"localizedValue": "2%"…]
},
{
"localizedAspectName": "Scent",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "MULTI", "aspectMode": "FREE_TEXT", "aspectRequired": false,…},
"aspectValues":[{"localizedValue": "Almond" }, {"localizedValue": "Apple" }, {"localizedValue": "Apricot"…]
},
{
"localizedAspectName": "Skin Type",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "SINGLE", "aspectMode": "FREE_TEXT", "aspectRequired": false,…},
"aspectValues":[{"localizedValue": "All Skin Types" }, {"localizedValue": "Blemish Prone" }, {"localizedValue": "Combination Skin"…]
},
{
"localizedAspectName": "Country/Region of Manufacture",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "SINGLE", "aspectMode": "SELECTION_ONLY", "aspectRequired": false,…},
"aspectValues":[{"localizedValue": "Unknown" }, {"localizedValue": "Afghanistan" }, {"localizedValue": "Albania"…]
},
{
"localizedAspectName": "Department",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "SINGLE", "aspectMode": "FREE_TEXT", "aspectRequired": false,…},
"aspectValues":[{"localizedValue": "Men" }, {"localizedValue": "Unisex" }, {"localizedValue": "Unisex Kids"…]
},
{
"localizedAspectName": "Expiry Date",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "SINGLE", "aspectMode": "FREE_TEXT", "aspectRequired": false,…}
},
{
"localizedAspectName": "Set Includes",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "MULTI", "aspectMode": "FREE_TEXT", "aspectRequired": false,…}
},
{
"localizedAspectName": "Unit Quantity",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "SINGLE", "aspectMode": "FREE_TEXT", "aspectRequired": false,…}
},
{
"localizedAspectName": "Unit Type",
"aspectConstraint":{"aspectDataType": "STRING", "itemToAspectCardinality": "SINGLE", "aspectMode": "SELECTION_ONLY", "aspectRequired": false,…},
"aspectValues":[{"localizedValue": "kg" }, {"localizedValue": "100g" }, {"localizedValue": "10g"…]
}
]
}

Full response added as attachment:

get_item_aspects_for_category.json

I am adding a bit more details of what each field means and what we want to use it for.

Note: Up to 30 values can be supplied for aspects that accept multiple values. Possible values: MULTI, SINGLE | | aspectMode | This indicates if we have a list of values which we must use. Possible values: FREE_TEXT, SELECTION_ONLY.

Please note for eBay we can have eBay values for both FREE_TEXT and SELECTION_ONLY however if we have SELECTION_ONLY we must use eBay values however if we have FREE_TEXT it is recommended to use eBay values. | | aspectRequired | Indicates if the attribute is required for the category | | aspectUsage | Here we have a 3rd type of attribute called Recommended so we gonna have: Required, Optional, Recommended. For the moment we want to indicate only the required attributes. | | aspectEnabledForVariations | Indicates if this attribute can be used for variation specifics | | aspectApplicableTo | N/A | | aspectValues | The list of values |

Taxonomy export file

In order to generate the taxonomy file we will need to create a new record in Taxonomy export with: Marketplace = ****eBay Status = pending Category for Export = all (or we can specify which exact categories) Country = Depends on the territories we want to support all countries as per this list Email = email to which the file will be send

Please find more details on the file structure how it should look like after exported here - Taxonomy General requirements . Also we would like to NOT include the skipped attributes in the taxonomy export file.

The file name need to be the category navigation path.

Please note we want to export the taxonomy files into a single zip file available for download

With the eBay taxonomy introduction we want to start using it for validations, however since we do not want to affect all current listings because the eBay integration works based on category ids not category paths we want to have additional option in Account Marketplace Ebay > Taxonomy Validation which indicates if its is True or False.

If we have Account Marketplace Ebay > Taxonomy Validation = Yes then we want to validate all listings when we are updating or creating either with the Trading API or the LMS. The validation process is as per our standards! The only thing which will be done differently is we also want to validate Product Account > Secondary Category ID like we do for Product Account > Primary Category ID