TikTok - Taxonomy - OLD

Summary of changes:

Delimiter for certificates; Delimiters for other fields corrected'; | | | 1.8 | 23/06/2022 | Added 2 new columns into taxonomy export; One of the column was renamed; | | | 1.9 | 28/07/2022 | Brand column added | | | 2.0 | 01/08/2022 | Added requirement for brand exporting | Section Get Brands, under New Requirement | | 2.1 | 09/08/2022 | Added requirements for brand file | | | 2.2 | 07/12/2022 | Brands file format | Change brands file format | | 2.3 | 03.09.2024 | Add size in skipped attributes | |

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 the product as Item Specifics according to their taxonomy which we download and store on the instance.

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

Get Category

API Call: GET /api/products/categories

API Docs: https://developers.tiktok-shops.com/documents/document/237493

Example Call:

https://open-api.tiktokglobalshop.com/api/products/categories?timestamp=1111&app_key=aaaa&access_token=aaa-aaa-aaa-aaa-aaa&sign=aaaaaaa&shop_id=111111

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

Into the response, we will have:

Example Response:

{
    "code": 0,
    "message": "Success",
    "request_id": "11111",
    "data": {
        "category_list": [
            {
                "id": "1",
                "parent_id": "1111",
                "local_display_name": "aaaa",
                "is_leaf": false
            },
            {
                "id": "2",
                "parent_id": "2222",
                "local_display_name": "bbbb",
                "is_leaf": false
            },
            {
                "id": "3",
                "parent_id": "3333",
                "local_display_name": "cccc",
                "is_leaf": false
            },
            {
                "id": "4",
                "parent_id": "4444",
                "local_display_name": "dddd",
                "is_leaf": true
            }
        ]
    }
}

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 Rule

As discussed, 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);

API Call: GET/api/products/categories/rules

API Docs: https://developers.tiktok-shops.com/documents/document/237496

Request Parameters:

Example Call:

https://open-api.tiktokglobalshop.com/api/products/categories/rules?timestamp=11111&app_key=aaa&access_token=aaaa-aaaa-aaaa-aaaaa-aaaaa&sign=aaabbb123&category_id=11111&shop_id=123456

Example Response:

{
  "code": 0,
  "data": {
    "category_rules": [
      {
        "product_certifications": [
          {
            "id": "123456",
            "is_mandatory": true,
            "name": "product_cert_name",
            "sample": "example"
          }
        ],
        "support_cod": false,
        "support_size_chart": true
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

We will receive success, only for category_id which “is_leaf=true“ for example, if we set id= "910728", and send the call, we will receive the following:

{
    "code": 0,
    "message": "Success",
    "request_id": "2022051312072101019106307425336F4C",
    "data": {
        "category_rules": [
            {
                "product_certifications": [
                    {
                        "id": "7080055018992862981",
                        "is_mandatory": false,
                        "name": "UKCA/CE mark",
                        "sample": "https://p16-oec-va.ibyteimg.com/tos-alisg-i-aphluv4xwc-sg/cc852dd13d8144ef9be17497264a3a7a~tplv-o3syd03w52-origin-image.image?"
                    },
                    {
                        "id": "7080055018992879365",
                        "is_mandatory": false,
                        "name": "UK / EU Declaration of conformity",
                        "sample": "https://p16-oec-va.ibyteimg.com/tos-alisg-i-aphluv4xwc-sg/1ea2418cde7b48d5adff8525a18db14c~tplv-o3syd03w52-origin-image.image?"
                    }
                ],
                "support_cod": false,
                "support_size_chart": false
            }
        ]
    }
}

But if we set id="1001992" ( "is_leaf"= false), we will receive following:

{
    "code": 12019002,
    "message": "category is invalid",
    "request_id": "2022051211255501018905313316898630",
    "data": null
}

• For most of the categories we will not receive product certification information:

{
    "code": 0,
    "message": "Success",
    "request_id": "202205260848250101920531421357ED84",
    "data": {
        "category_rules": [
            {
                "support_cod": false,
                "support_size_chart": false
            }
        ]
    }
}

This means, the product within this category does not need to be “certified“, and we are allowed to push a product for creation without this information.

If the “Category Rule“ call return product_certification information, this means we need to provide the certification_if & the file when creating a product.

Additional requirements

Docs: https://developers.tiktok-shops.com/documents/document/240047

From 30/06/2022 a new field for product identifier will be a requirement for all UK product listings. Product identifiers, or commonly known as Global Trade Identification Number (GTIN), are found in barcodes in GTIN/UPC/EAN/ISBN formats.

At the moment, because there is lack of information and payloads are not updated, our assumption is:

It will be mandate to push GTIN when creating and editing a product; However, TikTok gives possibility to “exempt“ products for some categories, i.e. to not push the GTIN.

Based on discussion we will proceed with the approach, where the GTIN will be mandatory for each listing! (will be described in details in “Create Product“ & “Full Update Product“.

Flow 1: (apply for exemption = NO) - We will approach with this flow!

The GTIN will be mandatory to be pushed, i.e. when calling create_product API to create a new product in UK we have to input GTIN into the request data, otherwise, the error message will be returned. When we have apply for exemption = NO, we need to make sure we have filled the GTIN into the request (TikTok will introduce new fields into the request for CreateProduct & Edit Product, which will be GTIN_type & GTIN_value). The GTIN type can be GTIN/EAN/UPC/ISBN and GTIN_value can be the value within the fields.

If we have filled the GTIN, it will be checked from TikTok system and if the GTIN is in valid format & correct, the request will pass successfully. If the GTIN is incorrect and invalid, error message will be returned.

Note: No action is required in Taxonomy export based on the new requirement! The described cases are located here too in order to have a clearance and details if we would want to build flow 2 in the future (If we decide to build flow 2, there might be some changes into the taxonomy export - at this stage NO CHANGES REQUIRED)

Flow 2: (apply for exemption = Yes) - N/A at this stage. Maybe will be build in future

When we have apply for exemption = Yes (most cases we need to apply for exemption when into we do not have filled GTIN). If there is such case, we should use GetCategoryRule API and there will be new node there “support_GTIN_exemption“. If “support_GTIN_exemption = Yes“, we should push ”exemption reason” in order to create/edit a product WITHOUT pushing the GTIN.

If “support_GTIN_exemption = No“, we should always provide a GTIN in create/edit a product.

Exemption reasons: (They are not official, there might be changes after 30/06/2022

[{
        "reason_code": 1,
        "description": "Brand/Manufacturer does not provide GTIN"
    },
    {
        "reason_code": 2,
        "description": "Generic, non-branded product without GTIN"
    },
    {
        "reason_code": 3,
        "description": "It is Product Bundle"
    },
    {
        "reason_code": 4,
        "description": "It is products' part that do not have GTIN"
    }
]

Example of the official payloads will be available on/after 30/06/2022

Possible errors codes & messages:

Get Attribute

API Call: GET api/products/attributes

API Docs: https://developers.tiktok-shops.com/documents/document/237495

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.

Request Parameters:

Example Call:

https://open-api.tiktokglobalshop.com/api/products/attributes?timestamp=1111&app_key=aaaa&access_token=aaaa-aaaa-aaaa-aaaa-aaaa&sign=bbbbbb&category_id=1234&shop_id=12345

Example Response:

{
    "code": 0,
    "message": "Success",
    "request_id": "1111111",
    "data": {
        "attributes": [
            {
                "id": "111",
                "name": "aaa",
                "attribute_type": 1,
                "input_type": {
                    "is_mandatory": true,
                    "is_multiple_selected": true,
                    "is_customized": true
                }
            },
            {
                "id": "222",
                "name": "bbb",
                "attribute_type": 2,
                "input_type": {
                    "is_mandatory": true,
                    "is_multiple_selected": true,
                    "is_customized": true
                }
            }
        ]
    }
}

is_mandatory - indicate if the attribute is mandatory;

is_multiple_selected - 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_customized - indicate if can push a custom value which is different from the suggested values from TikTok;

<v2.3> We want to exclude the Size attribute from the internal validation and despite if it required or not or part of the category attributes we want to push it to TikTok if added on the product. </v2.3>

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

Possible error codes & messages:

Get Brands

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 /api/products/brands

API Docs: https://developers.tiktok-shops.com/documents/document/237494

Example Call:

https://open-api.tiktokglobalshop.com/api/products/brands?timestamp=111111&app_key=aaaaaa&access_token=aaaa-aaaa-aaaa-aaaa-aaaaaddf&sign=abc123abc&shop_id=123456

Example Response:

{
    "code": 0,
    "message": "Success",
    "request_id": "111111111",
    "data": {
        "brand_list": [
            {
                "id": "1111111",
                "name": "aaa"
            },
            {
                "id": "2222222",
                "name": "bbb"
            }
        ]
    }
}

File with Brands:

GetBrands

Note(based on test API calls) : If we want to receive brands for a specific category, we should use the “category_id“ into the request and into the response, we will receive the brands for a specific category.

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.

New Requirement:

****As per performed tests, the QA noticed there isn’t a brand column into the taxonomy export file. Based on this and further communication with TikTok, we would want the brands to be exported in separate file CSV file.

The main reason is we will not receive a specific brand for a specific category, i.e. if into the Get Brands request parameters we specify the category_id, into the response will not be returned the brands specified only for this category_id, but will be returned all brands!

The above issue was confirmed with TikTok - expected behavior is to return all available brands, no matter if we have specified a category ID.

File format

Additional Information:

• Workflow steps

Create Product flow: (focusing on 1,2,3 & 5 for the purpose of this section)

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

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