[Action Required] Sandbox Testing for Category Tree Adjustment in June 2021

Hi Developer,

Thank you for your acknowledgement of Shopee’s Category Tree Adjustment announcement in February (previous announcement).

To ensure that you can be fully prepared and have enough time to adjust your category mapping logic, we have provided the new global category tree data in the Sandbox environment for your testing. This will be available from 30/04/2021 onwards for both v1 and v2 (whitelisted users) APIs.

The scheduled rollout to the Live environment will be between 7 June 2021 to 14 June 2021 for all sites, except for the BR site where it will not be rolled out.

Please note that:

• Before the Live environment rollout dates, the categories/attributes will be different between the Sandbox and Live environment.
• The exact rollout date and time will be announced again 10 days before the rollout schedule.

What to expect:

• The new category and attribute data can be extracted by GetCategories and GetAttribute APIs in the sandbox environment.
• All APIs that take category_id as request param need to request with leaf node category_id.
• More mandatory attributes will be added.

- For new listing creation, all mandatory attributes are required.

- For existing listing updates, there will be a transition period allowing for listings to be updated without filling in all the missing mandatory attributes.

(Exception: if you update category_id for an existing listing, all mandatory attributes of the new category_id should be included.)

• Parent-child structure will be introduced at the attribute level.

There are three types of parent-child attribute/brand structure:

1. parent(mandatory*) - child(mandatory)

2. parent(mandatory) - child(optional)

3. parent(optional) - child(optional)

*Mandatory from “is_mandatory” field in GetAttributes API

For Types 1 and 2, creating new listings will require the mandatory attributes.

For Type 3, you can use only parent or parent-child for new listings.

One child can have multiple parents, and it only needs one parent in the request for creating new listings.

Currently, all parent-child relationships are set up using Type 3.

• For OpenAPI 2.0, the brand field will be extracted from regular attributes and each brand will have a unique brand_id. For existing listings with unrecognised brand by Shopee and no valid brand_id assigned to it, the unrecognised brand will be wiped out and the listings will be considered as “no brand”.
• For OpenAPI 2.0, the attribute value_id will have a valid value instead of 0.
• New APIs for OpenAPI 2.0:

- v2.product.search_item for searching attributes-missing listings

- v2.product.category_recommend for global category recommendation based on listing name

How to test the new global category tree in Sandbox:

Refer to step 5 in the user guide to learn more about the Sandbox environment.

Main test cases for v1 developers:

1. Retrieve the new global category tree data in Sandbox by GetCategories and GetAttribute APIs.

2. Use the retrieved category_id, attribute_id and other necessary info to call item.Add and item.Update.

3. Based on the upload and update result, call GetItemDetail to verify.

Note: There is no parent-child structure indicator field in v1. If it is Type 3 structure and you only include the child but not parent, it will fail.

Additional cases:

1. Call GetCategoryByCountry to retrieve category_id to verify categories are the same across different markets.

2. Call GetRecommendCats to retrieve category_id based on the listing name.

Main test cases for v2 whitelisted developers:

1. Retrieve the new global category tree category_id in Sandbox by product.get_category

2. Call product.get_brand_list to retrieve the brand_id

3. Call product.get_dts_limit to retrieve the days-to-ship limit details

4. Call product.get_attributes to retrieve the attribtue_id, value_id and parent-child structure details

5. Use applicable category_id, attribute_id, value_id and brand_id to call product.add_item to create new listings.

6. Use category_id to call product.support_size_chart to check if size chart is supported for this category.

7. Call product.update_size_chart with the applicable category_id to upload size chart

Additional cases:

1. Call product.search_item to find listings that are missing mandatory or optional attributes after the new global category tree is released.

2. Call product.category_recommend to retrieve recommended category_id based on listing names.

For more details on the v2 test case call flow, please check here. (for whitslited developers)

OpenAPI 2.0 will be fully released by mid May 2021. A separate announcement will be sent to you soon, please pay close attention to our OpenPlatform.