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 (e.g., Item Specifics common to that category,) or sellers 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. Refer to Category Versioning for complete information.
  • 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. 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.

As with the active category hierarchy, category mappings vary for each eBay marketplace and the data have a version level. For a given marketplace, you can reduce the amount of data returned by only retrieving data that has changed since the last time you executed the call. The number of times the call is executed can be reduced by adhering to the following best practices:

  • Initially, call GetCategoryMappings with the value for DetailLevel set to ReturnAll and no CategoryVersion specified in order to retrieve 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 call GetCategoryMappings when the GetCategories response has not changed.

    Alternatively, determine whether the mappings have changed by using GetCategoryMappings with no DetailLevel value specified. 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 have determined that the mapping version has changed, call GetCategoryMappings with the value for DetailLevel set to 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.

    Thus, in January the 123-to-456 mapping is returned.

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

    • 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 following table.

Mappings Returned Old ID Active ID
January 123 456
May 123 789
May 456 789

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

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.