TikTok - Taxonomy

Summary of changes:

The purpose of this page is to detail how we can download different categories and their respective taxonomy from TikTok.

In order to download the taxonomy, we will use API calls. The taxonomy must be stored in classes, which should be available for exports from the UI in Export Taxonomy table. The taxonomy is used for internal validation and we will need to map the values and push the codes to TikTok.

Note: Every time we send products for creation we have to do internal check if all required attributes are part of the product as Item Specifics according to their taxonomy which we download and store on the instance.

The taxonomy will be the same for every account the only difference might be for the brands so we want to keep the brands per shop id.

The steps we need to follow in order to download the taxonomy are:

<v1.1.>

Get Categories

API Call: GET /product/202309/categories

API Docs: https://partner.tiktokshop.com/docv2/page/6509c89d0fcef602bf1acd9b?external_id=6509c89d0fcef602bf1acd9b

Example Call:

https://open-api.tiktokglobalshop.com/product/202309/categories?app_key=123abc&sign=5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c&timestamp=1625484268&locale=en-US

We use this call in order to get all available categories for TikTok.

We need to pass the shop_cipher as query property which was obtained with the Get Authorised Shops call.

Into the response, we will have:

Example Response:

{
  "code": 0,
  "data": {
    "categories": [
      {
        "id": "600002",
        "is_leaf": false,
        "local_name": "Home Supplies",
        "parent_id": "600001",
        "permission_statuses": "[INVITE_ONLY, NON_MAIN_CATEGORY]"
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Into the response, we have all the available categories for TikTok.

Please see file below with all categories for TikTok:

Categories

Possible error codes & messages:

Please note, that we need to incorporate in 1 cron Get Category & Get Category Rule call (described below). And also, we can receive category rules only for categories, which "is_leaf": true.

Get Category Rules

As advised, we need to incorporate this call with “Get Category“ into 1 cron. “Get Category Rule“ will be part of taxonomy classes as attributes for each category;

We can get category rule, using category_id parameter

Get Category rule parameter gives us information whether to upload sizechart, whether to upload product qualifications, whether to support COD (cash on delivery). Please note that only leaf category IDs are supported for obtaining category rules.

API Call: GET /product/202309/categories/{category_id}/rules

API Docs: https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9?external_id=6509c0febace3e02b74594a9#Back To Top

Request Parameters:

We need to pass the shop_cipher as query property which was obtained with the Get Authorised Shops call. We also want to pass category_version = v2 as property so we get the latest category version.

Example Call:

https://open-api.tiktokglobalshop.com/product/202309/categories/600001/rules?app_key=123abc&sign=5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c&timestamp=1625484268

Example Response:

{
  "code": 0,
  "data": {
    "cod": {
      "is_supported": true
    },
    "epr": {
      "is_required": false
    },
    "package_dimension": {
      "is_required": true
    },
    "product_certifications": [
      {
        "id": "602362",
        "is_required": true,
        "name": "SNI Certificate",
        "sample_image_url": "https://p-boei18n.byted.org/tos-boei18n-i-jvtte31kaf/80b32f2896829eeb69d4b278c4f3aa75.jpg~tplv-jvtte31kaf-origin-jpeg.jpeg"
      }
    ],
    "size_chart": {
      "is_required": true,
      "is_supported": true
    }
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Get Attributes

API Call: GET /product/202309/categories/{category_id}/attributes

API Docs: https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8?external_id=6509c5784a0bb702c0561cc8#Back To Top

Using this API call, we will get all information available for attributes in each category. In order to do this, we need to use category_id and we could map attributes to respectively category.

Input a category to get the required product attributes and sales attributes that are required to list the product. We can specify the language using the locale parameter. This API returns the required attributes based on where your shop is currently based. Please note that only leaf category IDs are supported for obtaining attributes.

<v1.3> TikTok frequently alternates between using "Color" and "Colour" as attributes, creating potential inconsistencies. To address this, we want to make these attributes interchangeable in Hemi. During validation, both versions should be recognized. For instance, if "Color" is listed as an Item Specific in Hemi but the taxonomy uses "Colour," our system should still pass the internal checks and allow the product to proceed for update or creation. **</v1.3>

<v1.4> We want to ignore the internal validation for Size attribute if we have categories which does not have size as part of the attributes. Also if we are skipping the validation for the Size we will always push it as a sale_attribute (Variation Specific). </v1.4>**

Request Parameters:

We need to pass the shop_cipher as query property which was obtained with the Get Authorised Shops call. We also want to pass category_version = v2 as property so we get the latest category version.

Example Call:

https://open-api.tiktokglobalshop.com/product/202309/categories/600001/attributes?app_key=123abc&sign=5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c&timestamp=1625484268&locale=en-US

Example Response:

{
  "code": 0,
  "data": {
    "attributes": [
      {
        "id": "100392",
        "is_customizable": true,
        "is_multiple_selection": true,
        "is_requried": false,
        "name": "Occasion",
        "type": "PRODUCT_PROPERTY",
        "values": [
          {
            "id": "1001533",
            "name": "Birthday"
          }
        ]
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

is_required - Indicate whether the attribute is required when creating or editing a product. is_requried is only applicable to product attributes. If is_required = true, it means that the product attribute is mandatory when listing the product.

is_multiple_selection - Whether the attribute value supports multiple selection; i.e. if is multiple selected=true, this means we can assign multiple values to one attribute(repeatable); if is “false“, we are allowed to push only 1 value to attribute;

is_customizable - Indicate whether the attribute value supports customization when creating or editing a product. is_customizable only applies to product attributes. If is_customizable = true, indicates that when listing the product, the product attribute allows the merchant to fill in custom sales attribute values.

Into the response, we have all the available attribute for each category for TikTok Marketplace.

Possible error codes & messages:

Get Brands

Use this API to retrieve all product brands by page token in the system. It will include both the platform's built-in brands as well as the custom brands created by sellers.

We will be storing brands as a part of the taxonomy (as attributes, applicable for each category) separated by Shop IDs. This is because we will receive different brand_list for the different shop IDs.

API Call: GET /product/202309/brands

API Docs: https://partner.tiktokshop.com/docv2/page/6503075656e2bb0289dd5d01?external_id=6503075656e2bb0289dd5d01#Back To Top

We need to pass the shop_cipher as query property which was obtained with the Get Authorised Shops call.We also want to pass category_version = v2 as property so we get the latest category version.

Example Call:

https://open-api.tiktokglobalshop.com/product/202309/brands?app_key=123abc&sign=5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c&timestamp=1625484268&category_id=600006&is_authorized=true&brand_name=Teas&page_size=100&page_token=b2Zmc2V0PTAK

Example Response:

{
  "code": 0,
  "data": {
    "brands": [
      {
        "authorized_status": "UNAUTHORIEZD",
        "brand_status": "AVAILABLE",
        "id": "7082427311584347905",
        "is_t1_brand": true,
        "name": "Teas"
      }
    ],
    "next_page_token": "b2Zmc2V0PTAK",
    "total_count": 10000
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Sample file with Brands:

GetBrands

Possible error codes & messages:

Note: Once we save the taxonomy, if we would like to update it, we need to delete the old taxonomy and simply to follow the steps above again, in order to get the new one.

</v1.1>

Taxonomy export file

In order to generate the taxonomy file we will need to create a new record in Taxonomy export with: Marketplace = TikTok Status = pending Category for Export = all (or we can specify which exact categories) Email = email to which the file will be send

<v1.2> We want to have a logic and if the user has selected 5 or more categories for export, we want to export them in a single zip file. This will be valid also if all categories are being exported. </v1.2>

Please find example file structure how it should look like after exported. We store for each category separate file.

Brands file format