eBay periodically adjusts a marketplace's category hierarchy to meet the current needs of eBay members and the marketplace. These kinds of changes are intended to make it easier for buyers to find items they are seeking and to help sellers list their items where buyers are most likely to look for them. For example, eBay can make the following kinds of category changes:

  • Add a new category for a new kind of item.
  • Split an existing category into multiple categories to help users differentiate items.
  • Combine multiple categories into a single category to make very similar items easier to find.
  • Allow a category that is rarely used to expire without being combined with other categories.
  • Add new metadata about the features a category supports (e.g., reserve prices).

When eBay combines a category with another category (or splits a category into multiple categories), we move any active and scheduled items from the old category into the appropriate active category. In this case, we update the category information stored on the items. This is necessary to make sure that the items will appear when users browse and search for items. For example, this ensures that GetItem and related calls always return the item's current category.

Thus, it can also be useful to synchronize listings that have been submitted by your users, to ensure that the categories and other data of items you have stored locally match the data that is currently in use for those items on the eBay marketplace. Use calls such as GetSellerList and GetSellerTransactions to perform such tasks.

This means the available list of categories changes periodically. After retrieving a marketplace's category data, your application should store the information in some persistent form, such as in a database table. Some category IDs can change as part of this process. If you create, revise, or relist an item with a Category ID that no longer exists — or never did exist — the listing request will fail. However, the Add/Revise/Relist calls in the Trading API have a feature that will allow eBay to remap an old Category ID to the current Category ID. Refer to Category ID mapping for additional information.

Periodically, your application should refresh the locally stored category data by synchronizing it with the latest metadata on the eBay marketplace. This is an important part of making sure a seller's listing data is valid.

Typical cases in which even a new listing's category information might be outdated include:

  • An application's locally stored category metadata was out of date when the seller defined their listing. This might occur with a client application that allows a user to define listings offline without first making sure their locally stored metadata is synchronized with eBay's data.
  • An application supports the ability to take an existing (previously defined) item and sell a similar item. For example, if the seller sold an item six months ago and now wants to sell a similar one, the application retrieves the old item's details from a local database and uses the information to pre-fill the details of a new listing. However, the old item's category and other data may no longer be valid on the marketplace.
  • An application allows a user to create a listing in advance of the start date and then schedule the listing to become active at a later date (often called a pending or scheduled listing). Even if the locally stored metadata is synchronized with eBay's data at the time the listing is defined, the listing details may be out of date by the time the application submits the information to eBay.

    Note: The easiest way to create scheduled listings and ensure that their details will be valid when the listing date arrives is to use eBay's built-in listing scheduling functionality. Rather than creating a listing locally and submitting it later, call AddItem (or similar API), specify the desired start date for the listing in the Item.ScheduleTime field, and submit the item immediately. When the scheduled time arrives, eBay updates the category and other information for you and the listing becomes active. This means no additional validation is required on your part, even if the category ID or other metadata has changed on the marketplace.

For information about keeping category information up to date, refer to: