When you add, 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 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 provided 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 every 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 process for using the category mapping feature is:

  • Include the Item.CategoryMappingAllowed field in an Add/Revise/Relist call and set to true or omit the field as its default value is true).

    If the category ID passed in the request no longer exists in the marketplace'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 argument (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 Item.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 stored category metadata is current. Refer to Category Versioning for additional information.

If the seller prefers not to allow eBay to perform category mapping on their behalf, refer to Client-Side Mapping for additional information.

If you prefer not to map categories locally and the seller chooses not to allow eBay to perform category mapping:

  • Include Item.CategoryMappingAllowed and set its value to false

    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 and then prompt the seller to choose an active category. Refer to Category Versioning for additional information.

The Item.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 was 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 Item.CategoryMappingAllowed argument will not have any effect and an error will indicate that the category is invalid.