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:

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. 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. See the Mapping Old Category IDs to Current IDs section for more information.

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:

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 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 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:

  1. The first time your application retrieves the categories for a particular site, use GetCategories with 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.
  2. 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.
  3. 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).

Old Categories Combined Into Active Categories
 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 a recently-created listing can have a deprecated 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:

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. 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).

Item Specifics Pre-filled Based on Old Categories
 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:

Using eBay's Category Mapping Feature

When you create, revise, or relist an item using the Trading API, the Item.CategoryMappingAllowed flag allows eBay to handle the cases in which the primary and/or secondary category ID specified in the request is no longer valid. The Item.CategoryMappingAllowed value is actually true by default, so a seller can either omit this field, or include it and make sure it is set to true. When the Add/Revise/Relist call is submitted, eBay validates the category ID(s), and if a deprecated category ID is used, eBay will automatically remap the old ID to the new category ID (as long as eBay has this mapping information). 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.

The full process for using the category mapping feature is shown below:

  1. Include the Item.CategoryMappingAllowed field in an Add/Revise/Relist call and set to true (or, just omit the field as its default value is true).
  2. If the category ID passed in the request no longer exists in the site's hierarchy, 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.

  3. 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 stored category metadata is current (see Checking the Category Hierarchy Version).

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:

  1. Include the Item.CategoryMappingAllowed field and set its value to false
  2. If a category ID passed in the request no longer exists, the call returns an error.

  3. 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 common to that category), or sellers who prefer not to allow eBay to drop invalid data:

  1. 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).
  2. 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.

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:

  1. 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.
  2. 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.
  3. 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.

  4. 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 nor does it 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:

  1. In January, eBay maps category 123 to category 456.
  2. Thus, in January the 123-to-456 mapping is returned.

  3. In May, eBay maps category 456 to category 789.
  4. Category mappings are transitive, so in May category 123 is now also mapped to category 789.

    Thus, in May, two mappings are returned:

    • One for the 123-to-789 mapping
    • One for the 456-to-789 mapping.
    • The previous 123-to-456 mapping is no longer returned because 456 is no longer an active category.

This logic is also illustrated in the table below.

Table: Category Mappings Over Time
Mappings Returned Old ID Active ID
January 123 456
May 123 789
May 456 789

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 the getItemAspectsForCategory method of the Taxonomy API to determine which item specifics might be available for the new category.