Recommend Global Categories

POST

/product/202309/global_categories/recommend

Retrieve a recommended leaf category and its category hierarchy for a candidate global product based on its title, description, and images. If you are syncing product catalogs from an external system to TikTok Shop, use this API to facilitate product classification. Note: Double-byte characters (e.g. Chinese characters) are not supported in text fields such as descriptions and titles. If you include them, the API request will fail.

Authorizations

• accessToken

Request Body^required

Media typeapplication/json

object

product_title

required

The product title. Title length:

• DE, ES, FR, IE, IT, JP, UK, US: [1, 255]
• MX:[1,300]
• Other regions: [25, 255]

string

description

The product description in HTML format.

Note:

• The content must conform to the HTML syntax. All HTML tags are accepted but to optimize display on the TikTok Shop product detail page, the system will automatically convert certain tags into alternative formats, such as rendering <table> tags as images.
• Max length: 10,000 characters.
• Image guidelines: You must use TikTok Shop image URLs. Max 30 <img> tags, each under 4000px with src, width, and height attributes.

Recommendations:

• If you are syncing a pre-existing description from another platform, include the full HTML source description here.
• Provide a detailed description, ideally over 300 characters.
• Include 3-5 key selling points, each under 250 characters, with supporting images.
• Use 1600x1600 px for the image dimensions.

string

<= 10000 characters

images

Product images, including gallery images, images that appear in the description, product variant images.

Array<object>

object

uri

The URI of the size chart image. Use the Upload Product Image API to upload the image first and obtain the corresponding image URI.

string

category_version

The category tree version to use for this product. Possible values based on region:

• US: v2, represents the 7-level category tree. Important: If the seller account contains an active US shop, you must pass v2 when using this API.
• Other regions: v1, represents the 3-level category tree. Default: v1

string

Allowed values: v2 v1

Example

{
  "product_title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short",
  "description": "<p>Please check the measurements before purchase.</p>\n<ul>\n  <li>M-Size</li>\n  <li>XL-Size</li>\n</ul> \n<img src=\"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/181595ea7d26489284b5667488d708c1~tplv-o3syd03w52-origin-jpeg.jpeg?from=1432613627\" width='100' height='100' /> \n ",
  "images": [
    {
      "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
    }
  ],
  "category_version": "v1"
}

Responses

200

Success

Media typeapplication/json

object

code

Status code; 0 means success.

integer format: int64

message

Success or failure message.

string

request_id

Request log ID.

string

data

object

leaf_category_id

The recommended category ID. This is always a leaf category.

string

categories

The category hierarchy for the recommended leaf category, ordered from the top-level category to the leaf category.

Array<object>

object

id

The category ID.

string

name

The category name.

string

level

The category level.

integer format: int64

is_leaf

A flag to indicate if the category is a leaf category. Note: You can only create or edit products that belong to a leaf category.

boolean

Example

{
  "code": 0,
  "data": {
    "leaf_category_id": "605254",
    "categories": [
      {
        "id": "605254",
        "name": "Christmas Gifts",
        "level": 3,
        "is_leaf": true
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}