Skip to content
TikTok Shop Partner API

Recommend Category

POST
/product/202309/categories/recommend

Retrieve the recommended category for a candidate 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 categorization. Note: The language used in text fields such as descriptions and titles must align with the target market’s language (e.g. don’t use Chinese).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
shop_cipher
required
string

Identifies the shop. Obtain it from the Get Authorized Shops API.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
category_version

Filter categories by the category tree version.Possible values based on region:

  • US, EU and SEA: v2, represents the 7-level category tree. Important: For US, EU and SEA shops, you must pass v2 when using this API.
  • Other regions: v1, represents the 3-level category tree.Default: v1
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
include_prohibited_categories

A flag to indicate whether to include matching categories that are prohibited on TikTok Shop. Set this to true to identify if the product falls under a category that you can’t list on TikTok Shop in any circumstances. Note:

  • Applicable only for BR and MX markets.
  • Default: false
boolean
listing_platform

Recommend categories that belong to the specified platform. Possible values:

  • TIKTOK_SHOP
  • TOKOPEDIA Default: TIKTOK_SHOP

Applicable only for sellers that migrated from Tokopedia.

string
Allowed values: TIKTOK_SHOP TOKOPEDIA
locale

The BCP-47 locale codes for displaying category information. Default: The default locale of your shop. Possible values:

  • cs-CZ
  • de-AT
  • de-BE
  • de-DE
  • el-GR
  • en-GB
  • en-IE
  • en-US
  • es-ES
  • es-MX
  • fr-FR
  • fr-BE
  • hu-HU
  • id-ID
  • it-IT
  • ja-JP
  • ms-MY
  • nl-NL
  • nl-BE
  • pl-PL
  • pt-BR
  • pt-PT
  • th-TH
  • vi-VN
  • zh-CN
string
Allowed values: cs-CZ de-AT de-BE de-DE el-GR en-GB en-IE en-US es-ES es-MX fr-FR fr-BE hu-HU id-ID it-IT ja-JP ms-MY nl-NL nl-BE pl-PL pt-BR pt-PT th-TH vi-VN zh-CN
origin_platform_product_type

The product type defined on the source platform.

string
origin_platform_vendor

The product vendor or brand name on the source platform.

string
origin_platform_tags

Tags associated with the product on the source platform.

Array<string>
origin_platform_category

Category information assigned to the product on the source platform.

object
id

The category ID on the source platform.

string
name

The category name on the source platform.

string
full_name

The full category path or full category name on the source platform.

string
is_leaf

Whether the category is a leaf category.

boolean
is_root

Whether the category is a root category.

boolean
origin_platform_product_meta_data

Additional product metadata provided by the source platform.

object
attribute_value_list

A list of product metadata attributes and their values.

Array<object>
object
name

The metadata attribute name.

string
values

The values associated with the metadata attribute.

Array<string>
product_title
required

The product title. Title length:

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

False — NORMAL products true — LIVE_QUICK products. Only seller with the required permissions can creat LIVE_QUICK products. Default: false

boolean
Example
{
  "category_version": "v1",
  "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' />",
  "images": [
    {
      "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
    }
  ],
  "include_prohibited_categories": false,
  "listing_platform": "TIKTOK_SHOP",
  "locale": "en-US",
  "origin_platform_product_type": "Handbags",
  "origin_platform_vendor": "Chanel",
  "origin_platform_tags": [
    "blastcornhole",
    "Shopify Collective"
  ],
  "origin_platform_category": {
    "id": "gid://shopify/TaxonomyCategory/na",
    "name": "Uncategorized",
    "full_name": "Uncategorized",
    "is_leaf": true,
    "is_root": true
  },
  "origin_platform_product_meta_data": {
    "attribute_value_list": [
      {
        "name": "mark_out_of_stock",
        "values": [
          "true"
        ]
      }
    ]
  },
  "product_title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short",
  "is_live_quick": false
}

Responses

Section titled “Responses”

200

Section titled “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
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
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
level

The category level.

integer format: int64
name

The category name.

string
permission_statuses

The shop’s permission status for this category. Possible values:

  • AVAILABLE: You have the permission to create products in this category.
  • INVITE_ONLY: This is a restricted category and you do not have permission to use it. Submit an application through the Qualification Center on TikTok Shop Seller Center to gain access. In Seller Center, INVITE_ONLY is also known as “restricted”.
  • NON_MAIN_CATEGORY: This category is not in the shop’s main category.
  • PROHIBITED: This category is prohibited on TikTok Shop. If your product falls under this category, do not attempt to list it, as it will be rejected during audit. Applicable only for BR and MX markets.
Array<string>
Allowed values: AVAILABLE INVITE_ONLY NON_MAIN_CATEGORY PROHIBITED
leaf_category_id

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

string
Example
{
  "code": 0,
  "data": {
    "categories": [
      {
        "id": "605254",
        "is_leaf": true,
        "level": 1,
        "name": "Teas",
        "permission_statuses": [
          "INVITE_ONLY"
        ]
      }
    ],
    "leaf_category_id": "605254"
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec