A CategoryID is a unique value associated with every eBay category. The CategoryID is generally used when using API calls to identify a category.

Categories and the category hierarchy will vary from one eBay marketplace to the next. For example, the category hierarchy and available categories on the US eBay marketplace varies from the eBay Germany marketplace. For categories that are basically the same, but on different marketplaces, the CategoryID value may be the same, but the category name may vary slightly, and the category name is always localized into the default language for the marketplace. Each eBay marketplace will have unique categories that are only of regional interest, or of interest to a particular culture.

You can use the Trading API's GetCategories call to retrieve all categories for a specific eBay marketplace. This call can also be used to retrieve a subset of the category hierarchy. For example, a user may just want to grab all categories under the Collectibles L1 category. Categories and/or the category hierarchy on an eBay marketplace are typically updated about once per quarter. An application could download the categories once and then periodically run the GetCategories call to check if the CategoryVersion and/or UpdateTime values has changed.

Category IDs are unique, but category names are not. For example, several categories currently exist called "Fantasy." Each of these categories is located in a different part of the category hierarchy, and each is assigned a different category ID, as illustrated in the following example.

Category Hierarchies for Different "Fantasy" Categories 

Dolls & Bears (237)
    Dolls (238)
        Art Dolls-OOAK (2404)
            Fantasy (84626)
        By Material (15999)
            Porcelain (45444)
                Contemporary (1980-Now) (48958)
                    Fantasy (48961)
Toys & Hobbies (220)
    Action Figures (246)
        Fantasy (175693)
    Games (233)
        Miniatures, War Games (16486)
            Warhammer (31398)
                Fantasy (44409)
        Role Playing Games (2543)
            Fantasy (44111)

Note: The category hierarchy is subject to change, and as of this writing, the above example is a "snapshot" of the categories named "Fantasy."

The combination of the CategoryArray.Category.CategoryID, CategoryArray.Category.CategoryParentID, and CategoryArray.Category.LeafCategory provide the information necessary to represent the category hierarchy. With these values, you can traverse the hierarchy and enable users to drill down from higher-level categories to lower-level categories.

For example, an application might initially present a list of categories that are all at the same level. These are categories that all have the same CategoryArray.Category.CategoryLevel values. Of these categories, some will be non-leaf categories. To drill down into the next level of one branch of the hierarchy, the application would use the CategoryArray.Category.CategoryID of one of the non-leaf categories and then load all categories where the CategoryArray.Category.CategoryParentID is the same as that CategoryArray.Category.CategoryID, essentially loading all of that category's children. To drill down to the bottom of the category branch, this process can be repeated as many times as necessary until all the child categories are leaf categories (i.e., the CategoryArray.Category.LeafCategory field appears as true).

These fields can also be used to "walk" upwards in the hierarchy. To do that, find the category for which the CategoryArray.Category.CategoryID equals the CategoryArray.Category.CategoryParentID of the current category (i.e., find the current category's parent). To find sibling categories, find all of the parent category's child categories (i.e., those categories for which the CategoryArray.Category.CategoryParentID is the same as the CategoryArray.Category.CategoryID of the current category). You can use this information to design and present category-selection functionality in your application.

Refer to Category Versioning for information about how to use the time stamp and version information returned by GetCategories to refresh the locally stored category meta-data after it has been initially downloaded.

For more information about how sellers select appropriate categories, refer to Adding a category to your listing.

For more information about how buyers look for items, refer to How to use search.