Maintaining Category Data
Changes in Category Requirements
Checking the Category Hierarchy Version
Mapping Old Category IDs to Current IDs
Changes in Category Requirements
eBay periodically adjusts a site'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 site. Use calls like GetSellerList and GetSellerTransactions to perform such tasks.
This means the available list of categories changes periodically. After retrieving a site'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. This means that when you submit a listing to eBay, it is possible that the category ID will no longer exist on eBay and the listing request will fail. (Similarly, if you pass an old category ID in a search request, the request may fail.)
Periodically, your application should refresh the locally stored category data by synchronizing it with the latest metadata on the eBay site. This is an important part of making sure a seller's listing data is valid.
Here are some typical cases in which even a new listing's category information might be outdated:
- Your application's locally stored category metadata was out of date when the seller defined the 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.
- Your 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 site.
- Your 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. Instead of creating the listing locally and submitting it later, you specify the listing start date in the Item.ScheduleTime property 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 site.
The following sections describe some of the ways you can keep your locally stored category information up to date.
Checking the Category Hierarchy Version
The category hierarchy for a given site is versioned. To check the category hierarchy version:
- The first time your application retrieves the categories for a particular site, use a detail level value of
ReturnAll. This returns the category data and the version for that site's category hierarchy. Store this value for future use.
- When the application next seeks to refresh the category data for that eBay site, call GetCategories with no detail level specified. This causes GetCategories to return only the category hierarchy version.
- Compare this newly retrieved version number with the one retrieved in the last call:
- If the newly retrieved version number is different, call GetCategories again but with a detail level of
ReturnAll to retrieve the category data. Store the new version number as the reference point for the next call.
- If the new and stored version numbers are the same, then category data does not need to be retrieved for that site at that time.
Note that changes to the category hierarchy of one site are independent of changes to another site. The category hierarchy version must be checked separately for each eBay site the application supports, using the procedure described here.
The eBay category hierarchy is updated on a monthly basis, but may be updated more frequently. It is a good idea to use GetCategories to check the category tree version at least once on each day that the application is being used.
Mapping Old Category IDs to Current IDs
The ID for a category in which you list an item can change. eBay might split categories to help users distinguish between items more easily or combine multiple categories to make very similar items easier to find. (In some cases, eBay may allow a category that is rarely used to expire without being combined with other categories.)
The figure below shows an example of three leaf categories (Frames, Cannondale, and Specialized) that were combined into a single leaf category (Complete Bikes & Frames).
Figure: Old Categories Combined Into an Active Categories
A common way to determine whether a category ID is current is to make sure your locally stored category metadata is current (see Checking the Category Hierarchy Version) and then verify that the ID exists in the current metadata. (To be valid in listing requests, the category ID also must be a leaf category.) In certain cases, even an item your application recently defined can have an old category ID (see Maintaining Category Data for examples).
If a seller wants to list an item that was defined with an old category ID, you can handle the situation in different ways:
- Allow eBay to attempt to update the category for you. This approach may be more convenient for sellers who are listing hundreds of items at once. In some cases, invalid data may be dropped from the listing, but the listing will still be submitted successfully. See Using eBay's Category Mapping Feature for information about this approach.
- Update the category information on the client side. This approach may be more convenient for sellers who use listing features that are highly dependent on the category (such as reserve prices) or who prefer not to allow eBay to drop invalid data. See Mapping Categories on the Client Side.
If the old categories were combined into a more general category, the original differentiation that the old categories provided may be lost. For example, the difference between "Cannondale" and "Specialized" would no longer be evident from the new "Complete Bikes & Frames" category. If the new category supports Item Specifics, eBay may offer Item Specifics that convey the same details as the original categories. In such cases, eBay may provide the ability to pre-fill these Item Specifics based on the old category.
The figure below shows an example of the way eBay uses old leaf categories (Cannondale and Specialized) to pre-fill corresponding Item Specifics (Brand=Cannondale and Brand=Specialized).
Figure: Item Specifics Pre-filled Based on Old Categories
If a seller wants to include Item Specifics that correspond to old category IDs, you can handle the situation in different ways:
- Allow eBay to attempt to pre-fill the Item Specifics based on the category (or categories). This approach may be more convenient for sellers who are listing hundreds of items at once. See Using eBay's Category Mapping Feature for information about this approach.
- Update the Item Specifics information on the client side. This approach may be more convenient for sellers who want more control over the Item Specifics that are selected. See Mapping Categories on the Client Side.
Using eBay's Category Mapping Feature
When you list an item, you can use the Item.CategoryMappingAllowed flag to allow eBay to handle the cases in which the primary or secondary category ID specified in the request is no longer valid. When set to
true, this flag allows eBay to check whether you are passing in old category IDs and, if you are, to map them to corresponding active IDs (if any exist). This enables listing requests with old categories to succeed without category validation errors. High-volume sellers may find it more convenient to submit listings in this manner instead of first updating all their categories each time.
In some cases, it is possible that when eBay maps an item's old category to an active category, eBay will drop certain data that is invalid for the active category. Therefore, it is a good idea to let the seller decide (through a standard preference or for each listing) whether or not to allow eBay to map a listing's categories in this manner during the listing flow.
To use this category mapping feature:
- Set the Item.CategoryMappingAllowed flag to true.
If a category ID passed in the request longer exists, eBay maps the old ID to the new ID and uses the new one for the listing instead. eBay returns the new ID in the CategoryID element (and Category2ID, or both, as appropriate) in the response.
If the category ID has not changed, no mapping occurs and the CategoryID (or Category2ID) element is not returned in the response. This means you can always specify CategoryMappingAllowed in listing requests even when you believe the item's categories are current.
- If category mapping occurs, update the category data on the locally stored item so that it is consistent with the item stored on eBay. Also make sure your application's locally store category metadata is current (see Checking the Category Hierarchy Version).
- It may also be possible to use Item Specifics to convey the same differentiation as the original category did. Let the seller decide whether or not to allow eBay to attempt to map the category to an item specific. To use this feature, set the Item.CategoryBasedAttributesPrefill flag to
If the category ID passed in the request has been mapped to an item specific, eBay includes the item specific in the listing's Item Specifics. See Mapping Old Category IDs to Current IDs for more information and other options.
If the seller prefers not to allow eBay to perform category mapping on their behalf, see Mapping Categories on the Client Side.
If you prefer not to map categories locally and the seller chooses not to allow eBay to perform category mapping:
- Set the Item.CategoryMappingAllowed flag to false (or do not specify it at all).
If a category ID passed in the request no longer exists, the call returns an error.
- If the call returns an error, make sure your application's locally stored category metadata is current (see Checking the Category Hierarchy Version) and then prompt the seller to choose an active category.
The CategoryMappingAllowed setting is transient. That is, it only applies for the current call; it is not stored with the item data. This means that when you revise or relist an item, it will not retain the originally category mapping preference that you specified in AddItem.
Some categories can expire without being combined with other categories. If the category ID you pass in AddItem or related call has expired in this manner, the CategoryMappingAllowed flag will not have any effect and an error will indicate that the category is invalid.
Mapping Categories on the Client Side
In some situations, you may need to update an item's category information on the client side before you list the item. For example, this approach may be more convenient for sellers who use listing features that are highly dependent on the category (such as Item Specifics) or who prefer not to allow eBay to drop invalid data:
- Before listing an item, compare its primary and secondary category IDs to the current category metadata. Make sure your application's locally stored category metadata is up to date (see Checking the Category Hierarchy Version).
- If the item's category data is no longer current:
- Prompt the user to choose a new category. In this case, you can suggest the active leaf category (if any) that is equivalent to the old category the seller originally chose.
- Alternatively, you can update the item's category information without prompting the user. Some applications allow the user to set a preference indicating whether to allow this.
To determine which active category has replaced an old category, use GetCategoryMappings (see GetCategoryMappings). The response provides a map between categories that are no longer active and the corresponding active categories. Multiple old categories can be mapped to the same active category.
Note: GetCategoryMappings only returns information about categories that have been mapped (i.e., combined categories and split categories). It does not return information about expired categories that have no corresponding active categories. When a category expires in this manner, any completed items that were listed in the expired category can still be found, but new listings cannot be created in the category.
Like the active category hierarchy, the category mappings vary for each eBay site and the data is versioned. For a given site, you can reduce the amount of data returned by only retrieving data that has changed since the last time you executed the call. You can also reduce the number of times you execute the call by using certain practices:
- Initially, use GetCategoryMappings with a DetailLevel value of
ReturnAll and no CategoryVersion to get all category mappings. Save the category mapping data locally, including the version value that is returned. This step should be performed at the same time you execute GetCategories so that the metadata returned from these calls is consistent.
- Mappings only change when the category hierarchy is updated. If the version returned from GetCategories does not change, you can assume the category mapping metadata also has not changed. That is, it is not necessary to execute GetCategoryMappings when the GetCategories response has not changed.
Alternatively, check whether the mappings have changed by using GetCategoryMappings with no DetailLevel value. This returns the current version information only (with no mappings). Compare the version with the last saved mapping version value to see if the mapping data has changed. If the version has not changed, it is not necessary to retrieve the mappings.
- When the category hierarchy changes (or you determine that the mapping version has changed), use use GetCategoryMappings with a DetailLevel value of
ReturnAll and specify the last saved mapping version value in the CategoryVersion input field. This limits the response to new and changed mappings since that version. Store the new CategoryVersion value returned and use it in the same manner the next time you execute this call.
GetCategoryMappings returns old and active category IDs but it does not distinguish between parent and leaf categories or return category names. Therefore, combine the results with information from GetCategories and related calls in order to build a complete set of information about each category. That is, match the active category IDs returned from GetCategories to the active category IDs returned from GetCategoryMappings in order to determine whether the old categories have been mapped to leaf categories or to display an active category name to the user.
Use the category mapping information to update category IDs defined on items that you plan to list on eBay.
GetCategoryMappings returns current mappings only (not historical mappings). For example, the mapping of a category could occur in this manner:
- In January, eBay maps category 123 to category 456.
Thus, in January the 123-to-456 mapping is returned.
- In May, eBay maps category 456 to category 789.
Category mappings are transitive, so in May category 123 is now also mapped to category 789.
Thus, in May two mappings are returned:
This logic is also illustrated in the table below.
Table: Category Mappings Over Time
Note: The category IDs in the above example are fictitious and are only used to illustrate the transitive nature of mappings. These values may or may not correspond to actual category IDs on an eBay site.
When eBay combines an old leaf category (e.g., Cannondale) with a more generic leaf category (e.g., Complete Bikes & Frames), eBay may instead use item specifics for the data that corresponds to the old category (e.g., Brand=Cannondale). Use GetCategorySpecifics to determine which item specifics might be available for the new category.
Copyright © 2005–2016 eBay Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.