An application can retrieve the entire eBay category hierarchy or one or more parent (non-leaf) categories as well as all or some of those categories' child categories. All GetCategories responses include the version number of the eBay category hierarchy, as well as a time stamp (i.e., UpdateTime,) to indicate when the last update to the hierarchy occurred. Generally, eBay updates the category hierarchy no more than once every few months. An application should be configured to check the category version occasionally and retrieve the category hierarchy only when it has been changed, thus saving unnecessary download time, activity, and bandwidth.

To retrieve the data for the categories for a particular eBay marketplace:

  • Set up the execution environment.
  • Specify the data to be returned (i.e., category hierarchy version or category hierarchy itself).
  • Call GetCategories.

Every category that satisfies the search filters is returned in the CategoryArray container. Each category is represented by a separate CategoryArray.Category container. The category data varies for different marketplacess. That is, the category hierarchy on the eBay US marketplace is not the same as the category hierarchy on the eBay Germany marketplace.

Optionally, specify the ID of one or more parent (non-leaf) categories and all (or some) of those categories' child categories. To determine available category parent IDs, retrieve and save all category data the first time GetCategories is called. The parent category of each returned category is returned in the CategoryArray.Category.CategoryParentID field. Note that top-level eBay categories, or L1 categories, do not have parent categories. The CategoryArray.Category.CategoryParentID field is still returned for L1 categories but this ID value is the actual ID of the L1 category, and the same value that will be returned in the CategoryArray.Category.CategoryID field for that category.

As mentioned earlier, the top-most categories in the eBay hierarchy have a level of 1 and their immediate children have a level of 2, and so on.

  • To retrieve all L1 categories but none of the children, the LevelLimit field would be included and set to 1.
  • To retrieve all L1 categories and their direct children (i.e., all L2 categories,) the LevelLimit field would be included and set to 2.

  • If the LevelLimit field is not used — or is used and set to a value greater than the "deepest" L1 category — all child categories down to the leaf categories are returned in the response.

    The CategoryArray.Category.CategoryLevel value is returned for every category in the response, and the value for the CategoryArray.Category.LeafCategory argument is returned as true for all leaf categories.

    Note: eBay items may only be listed in leaf categories.

Important! After retrieving the data for a marketplace's category hierarchy, the application should store the information for later use in some persistent form, such as in a database table. This data can then later be refreshed when a category hierarchy change is indicated (i.e., when the returned category hierarchy version is different than the last one the application retrieved). Although an application may use a transient storage method where the data exists only for the duration of the application's session, a persistent method of storing category data is preferred. If transient storage is used, the application must retrieve the category data from eBay each time the application is run. This is very inefficient and can be very time-consuming.

An application needs to traverse all CategoryArray.Category containers within the CategoryArray container of the response to inspect each category's ID and properties in order to store and work with the data in a useful way.

For details about how to invoke the various options and work with the response data, refer to the GetCategories reference documentation.

An application can use the returned category names to populate a browser from which the user can select the category in which to list a new item. The application should store the category data in some persistent manner (e.g., in a database table,) to have the data available whenever the application is run.