Marketplaces / TikTok Marketplace Integration v2 / TikTok - Product management / TikTok Create Products

TikTok Create Products

Version Date Created / Updated Notes
v1.0 20/06/2024 Hristiyan Georgiev TikTok has new API version and updates. The scope was also updated to the latest changes
v1.1 23/07/2024 Hristiyan Added additional logic for image upload
v1.2 29/07/2024 Hristiyan changed where we pick certification image and size chart image
v1.3 04/09/2024 Hristiyan Added logic for variant images
v1.4 05/09/2024 Hristiyan Changed the logic which images we pick for MAIN_IMAGE scene
v1.7 11/09/2024 Hristiyan Added logic for internal validation for package dimentions as they need to be integers
v1.8 30/09/2024 Hristiyan Added new status field
v1.9 13/11/2024 Hristiyan Changes in the sub images logic

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. Please see subsection TikTok - Taxonomy

Upload Images

When we are creating a product we are sending images too, but we have a separate call for “Upload images“, so we need first to call “Upload images“, to push images and then to download images ids, store them into TikTok Images table and then to use theimg_id to list the product.

API Call: POST /product/202309/images/upload

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

Example:

https://open-api.tiktokglobalshop.com/product/202309/images/upload?app_key=123abc&sign=5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c&timestamp=1625484268
Integration Field Integration Notes Integration required Hemi Mapping Hemi Notes
data string

Image file data to be uploaded to Tiktok Shop. The picture file is a string generated by binary. Prerequisites:

  • image formats support JPG, JPEG, PNG
  • image pixels at least 100 100 and at most 20000 20000
  • Max size of original image: 5MB | Yes | As per the images handling abstraction we want to pick all images ****that we have in Hemi. Please refer to below explanation. | Тhe images that we want to publish and then to use them when creating a product.

Note: As per confirmation , the picture pixels are 100 100 and at most 20000 20000 | | use_case | int32 By specifying the usage scenario of the image during the upload process with different parameters, the image will be processed into different sizes to meet the listing requirements. The usage scenarios include:

MAIN_IMAGE: Aspect ratios exceeding 3:4-4:3 will be cropped to fit within the range of 3:4-4:3. ATTRIBUTE_IMAGE:Aspect ratios exceeding 3:4-4:3 will be cropped to fit within the range of 3:4-4:3. DESCRIPTION_IMAGE:Keep the original image returned after uploading. CERTIFICATION_IMAGE:Keep the original image returned after uploading. SIZE_CHART_IMAGE:Keep the original image returned after uploading. | Yes | <v1.4> 1. MAIN_IMAGE - We want to use the first image from (4) Leading Images

  1. DESCRIPTION_IMAGE - N/A

  2. ATTRIBUTE_IMAGE We continue from the 2nd image from (4) Leading Images and also include (5) Additional Images </v1.4> 4.CERTIFICATION_IMAGE will be Product Account TikTok > Certification Image

  3. SIZE_CHART_IMAGE will be Product Account TikTok > Size chart image | Images handling abstraction can be found here: Images Handling Additional Explanation

<v1.4>We want to have a validation and if we don’t have any (4) Leading Images we want to return an internal error stating that there are no leading images.</v1.4> |

  • Important: We load all the images and we set the scene based on from which field we have taken the image.

We need to have images uploaded before we proceed creating a product; We should not pick a products for creation, if the images are not uploaded!

Example Response:

{
  "code": 0,
  "data": {
    "height": 720,
    "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe",
    "url": "https://p-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe\n",
    "use_case": "MAIN_IMAGE",
    "width": 720
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Response Mapping:

Integration Field Integration Notes Hemi Mapping Hemi Notes
code
data
height Height dimension of the image which is determined on upload. This is the height post processing. N/A
uri The URI returned from uploading the image, which can be used for product main image, SKU image, size chart image, qualification image, etc. when listing a product. TikTok Images > TikTok Image ID Table field with two columns. The first column would be for the Image ID and the second one - for the Image Scene.

For the name we would like to store the scene and the value will be the image id | | | url | The URL returned from uploading the image can be directly opened in a browser. It can be used in product description when creating a product. | N/A | | | | use_case | Return the usage scenario provided during the upload. The usage scenarios include: MAIN_IMAGE DESCRIPTION_IMAGE ATTRIBUTE_IMAGE CERTIFICATION_IMAGE SIZE_CHART_IMAGE | TikTok Images > TikTok Image Scene | Enum field ; For the name we would like to store the scene and the value will be the image id | | message | | | N/A | | | request_id | | | N/A | |

When we send the images we will have List/Update the Whole Item = Pending.

Once we start sending the image, we will set List/Update the Whole Item = Sent. (Only for those which were on “Pending“!)

Once the images were sent successfully, we will put List/Update the Whole Item back on Pending. (in order to be picked by the cron for create/update products)

Please note that we should set “Images Uploaded” status only for variants which were updated to “Sent”!

Note: We will have Product Status = Images Uploaded only if the product status was = Awaiting Creation or Removed. If it is published, we don’t touch the status

We will have a couple of validations:

1 The first will be to check if we have successfully pushed the images in order to download uri & URLs;

2 If we have id store or a specific scene , we need to override with the new one;

3 we will not pick product for creation, if images are not uploaded;

<v1.1> We want to implement a logic and if we have even one manage fail to upload, we want to block the creation of the product and store an error. </v1.1>


Create Product

We need to have images uploaded before we proceed creating a product; We should not pick a products for creation, if the images are not uploaded!

We need to identify for which category we need to push the product certification information. Then, if for a specific category this information is needed, we need to upload the certification image into the node product certification (we do not need to upload file because at this stage we will not use “UploadFile“ call), and to use the returned file_id for product creation. Also, we need to push the product certificate id, which is returned by “GetGatecoryRule“ call. We should not pick a product for creation, if the file is not uploaded (Only for products which required “Product Certification info”. More information regarding product certifications is available here TikTok - Taxonomy)

After sending the product for creation to marketplace, the product will be with status Suspended & Awaiting review. Once the review is successful - the product status will be set to “Live“ (Active). If the review is not successful, the product status will be Suspended & Failed.

**Important:*** If the cron pick a variant which need to be added to already published variation group, the listing create cron will pick the Channel Item ID and will assign it to the variant which we would want to publish. Also, the listing create cron should fill in the channel item ID only for variants on which have List/Update the Whole item = “Pending“ and Product Status = ”Images Uploaded”

We should be able to list product even if the table item account TikTok is empty, i.e. we do not have records. After successful product creation on TikTok, we should store the SKU ID, which is returned by TikTok into the table Product Account TikTok.

API Call: POST /product/202309/products

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

All triggers, validations etc are as per the abstraction -

Product Listing general requirements

We need to pass the shop_cipher as query property which was obtained with the Get Authorised Shops call found here TikTok - Authentication & Database structure

Example Call:

{
    "brand_id": "7082427311584347905",
    "category_id": "600001",
    "certifications": [
      {
        "files": [
          {
            "format": "PDF",
            "id": "v09ea0g40000cj91373c77u3mid3g1s0",
            "name": "brand_cert.PDF"
          }
        ],
        "id": "7182427311584347905",
        "images": [
          {
            "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
          }
        ]
      }
    ],
    "delivery_option_ids": "1729592969712203232",
    "description": " ",
    "external_product_id": "172959296971220002",
    "is_cod_allowed": false,
    "main_images": [
      {
        "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
      }
    ],
    "manufacturer": {
      "address": "123W 106th St, New York, NY, USA, 10025",
      "email": "samplemanufacturer101@outlook.com",
      "name": "Sample Manufacturer Name\n",
      "phone_number": "4412345678"
    },
    "package_dimensions": {
      "height": "10",
      "length": "10",
      "unit": "CENTIMETER",
      "width": "10"
    },
    "package_weight": {
      "unit": "KILOGRAM",
      "value": "1.32"
    },
    "primary_combined_product_id": "1729582718312380123",
    "product_attributes": [
      {
        "id": "100392",
        "values": [
          {
            "id": "1001533",
            "name": "Birthday"
          }
        ]
      }
    ],
    "save_mode": "LISTING",
    "size_chart": {
      "image": {
        "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
      },
      "template": {
        "id": "7267563252536723205"
      }
    },
    "skus": [
      {
        "combined_skus": [
          {
            "product_id": "1729582718312380123",
            "sku_count": 1,
            "sku_id": "2729382476852921560"
          }
        ],
        "external_sku_id": "1729592969712207012",
        "identifier_code": {
          "code": "10000000000000",
          "type": "GTIN"
        },
        "inventory": [
          {
            "quantity": 999,
            "warehouse_id": "7068517275539719942"
          }
        ],
        "price": {
          "amount": "1.21",
          "currency": "USD\n"
        },
        "sales_attributes": [
          {
            "id": "100089",
            "name": "Color",
            "sku_img": {
              "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
            },
            "value_id": "1729592969712207000",
            "value_name": "Red"
          }
        ],
        "seller_sku": "Color-Red-XM001",
        "sku_unit_count": "100.00"
      }
    ],
    "title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short Boat Invisible Socks",
    "video": {
      "id": "v09e40f40000cfu0ovhc77ub7fl97k4w"
    }
  }

Mapping (please note N/A means we exclude it from the payload):

TikTok Field Integration Notes Integration required Hemi Mapping Hemi Notes
brand_id string
We can only choose from brands that already have qualifications. No Product > Brand As per discussion we have agreed if we do not have filled brand, we will skip the node into the payload while sending the product;

If we have a value into the brand field, we will send the brand ID. *we fill in the brand name/label and then the integration should map it using the taxonomy and send the Brand ID.; | | category_id | | | | Must be a leaf category | Yes | Product Account> Primary Category ID | We need to use the values from column Category Path ( The column “Category Path“ from the Taxonomy Export file) | | certifications | | | | Based on the category the product belongs to, the product may require product certification. You can obtain the requirements for each category via the "Get Category Rule" API. | No | | | | | files | | | | | | | | | | format | | | | N/A | | | | | id | | | | N/A | | | | | name | | | | N/A | | | | id | | | This is the certification id , you can get this id by "GetCategoryRule"API. | Yes | Product Account TikTok > Certifications > Name | 2 columns - first column to be name, and the second one to be the URL; We will map the name from the taxonomy and use the ID; This ID is returned for some categories and we should store this ID as a part of the taxonomy. It is mandatory to push when the “CategoryRule“ return this information. | | | images | | | | | N/A | | | | | uri | | You can only use the response parameters of the Upload Image API as this request parameter | Yes | <v1.2>TikTok Images > TikTok Image ID</v1.2> | We would want to send all image ids from field Certification Image. We need to search the URL for the ceritification images scene into the TikTok Images table and send the ID; We need to group them by name; images here need to be send only if GetCategoryRule return “product certification“ information. At all, the information in certifications nodes need to be send ONLY if product certification is needed. More detailed explanations for GetCategoryRules call, you can find in “TikTok Taxonomy - GetCategoryRule“ section. | | delivery_option_ids | | | | This is an optional field. If we do not fill in this part of the information, the system will set this field as the "default" delivery option. | No | N/A | | | description | | | | HTML rich text of a product description to describe your product information in detail. | Yes | Product Account > Description | We would want to use the logic of design template. If we have design template we will pick the design template; If we haven’t design template, we will pick the default one. If we haven’t the default one, we will pick the description | | external_product_id | | | | The external_product_id is the product identifier for the external system. It is used to associate it with the product. The input character length can not exceed 999 | No | N/A | | | is_cod_allowed | | | | COD stands for Cash On Delivery, which is allowed by certain categories. You can check if your category allows COD through the 'GetCategoryRule' API. Set is_cod_allowed to be true if unsupported regions or categories are intercepted. If enabled, buyers can choose this payment method during checkout. | No | N/A | | | main_images | | | | We can only use the response parameters of the "Upload Image" API as the request parameters up to 9 pictures, The order of image arraylist will become the sequence of images. | Yes | | | | | uri | | | The image URI returned by the "Upload Image" API. | Yes | (2) Main Image(s), (1) Listing Image AND (3) More Images

from the TikTok Images using TikTok Image ID instead of url | The main images for the product

We would want to send maximum 9 pictures from these fields.

| | manufacturer | | | | | No | N/A | | | | address | | | | No | N/A | | | | email | | | | No | N/A | | | | name | | | | No | N/A | | | | phone_number | | | | No | N/A | | | package_dimensions | | | | | | | | | | height | | | string | Yes | Product >Height | By default, in Hemi the measure unit is “cm“. <v1.7> The package height must be a non-negative integer , so we need to have internal validation and return an error if we are trying to send non integer. Must be greater than 0 </v1.7> | | | length | | | string | Yes | Product >Length | By default, in Hemi the measure unit is “cm“ . <v1.7> The package length must be a non-negative integer, so we need to have internal validation and return an error if we are trying to send non integer. Must be greater than 0</v1.7> | | | unit | | | | Yes | | Hardcoded as “CENTIMETER” | | | width | | | string | Yes | Product >Width | By default, in Hemi the measure unit is “cm“ <v1.7> The package width must be a non-negative integer , so we need to have internal validation and return an error if we are trying to send non integer.Must be greater than 0 </v1.7> | | package_weight | | | | | | | | | | unit | | | The current system supports units including "KILOGRAM" and "POUND". | Yes | | Hardcoded as “KILOGRAM” | | | value | | | The package weight must be a positive number. | Yes | Product >Weight | In Hemi the measure unit for this field is “gram“ so we need to convert it into kilogram . <v1.7>The package weight must be a positive number so we need internal validation for that. </v1.7> | | primary_combined_product_id | | | | | No | N/A | | | product_attributes | | | | | | | These are the "type": "PRODUCT_PROPERTY" from the taxonomy | | | id | | | Only support the input of the product attribute ID that is provided by the platform(from Get Attributes API) | Yes | Product Account > Item Specific Name | part of Taxonomy. Based on the validation and mapping we need to push the actual IDs; | | | values | | | []object We can fill in the product attribute value information corresponding to the product attribute id. Optionally fill in either the product attribute value ID or the product attribute value name. If both are filled, the product attribute value ID will be prioritized | Yes | | | | | | id | | Only support the input of the product attribute id that is provided by the platform(from "Get Attributes" API) | No | <v1.6> Product Account > Item Specific Value OR Product Account > Variation Specific Value </v1.6> | | | | | name | | string This field is for you to fill in the custom attribute value. Here are some conditions of the field:

  • There are no language restrictions, but Chinese can not be used.
  • The maximum character is 500.
  • This field support submits multiple values, but these custom values can not be duplicated. | No | <v1.6> Product Account > Item Specific Value OR Product Account > Variation Specific Value </v1.6> | part of Taxonomy If we do not found the the value_name within the Taxonomy, we are able to push custom value here. | | save_mode | | | | save_mode is used to specify the saving mode for creating a product, supporting AS_DRAFT, LISTING. | No | | Hardcoded as “LISTING” | | size_chart | | | | The category_rule determines whether this parameter is required. If the category rule is "true", it must be filled in, and if the category rule is "false", it is not required | No | N/A | | | | image | | | | | | | | | | uri | | Only support the input of the sales attribute ID provided by the platform | Yes | <v1.2>TikTok Images > TikTok Image ID</v1.2> | this field need to be filled only if size_chart=true; If is not filled but it is required by taxonomy, error should be displayed; we need to use the image from the scene SIZE_CHART_IMAGE from the TikTok Images | | | template | | | The size chart template generated by the size chart tool | No | N/A | | | | | id | | Size chart template ID | No | N/A | | | skus | | | | | | | All variants of the product | | | combined_skus | | | For a combined listing SKU, an array of related product SKUs that compose the combined listing SKU | No | N/A | | | | | product_id | | | No | N/A | | | | | sku_count | | | No | N/A | | | | | sku_id | | | No | N/A | | | | external_sku_id | | | The external_sku_id is the sku identifier for the external system. It is used to associate it with the product sku | | Product > SKU | | | | identifier_code | | | | | | | | | | code | | string Identifier code logic:
    1. Must be a numeric type
    2. The number of characters needs to meet the requirements (GTIN: 14 digits, EAN: 8/13/14 digits, UPC: 12 digits, ISBN: 13 digits)
    3. Different SKUs are not allowed to use the same gtin code. | Yes | Product Account > Marketplace EAN OR Product > EAN OR Product > UPC OR Product > ISBN OR Product > Barcode | If we have filled value in Product > Barcode, we will push GTIN _value = the value in the field Barcode; If we have filled value in Product Account > Marketplace EAN (with priority) OR Product > EAN , we will push the GTIN _value = the value in the field EAN; If we have filled value in Product >UPC, we will push the GTIN _value = the value in the field UPC; If we have filled value in Product>ISBN, we will push the GTIN _value = the value in the field ISBN;

Once the GTIN has been assigned to an existing product, it can't be changed or deleted! For this reason we need to save the value we have pushed in GTIN field and use the value when performing update (Edit Product API). The specific here is we would want to display the value of this field, but into the UI, field to be read only. And also, we need to make sure if we delete a product, the information for GTIN also to be deleted.

Priority: EAN, UPC, ISBN, Barcode

Note: The field is mandatory to be pushed when we perform full update(edit) product. If not pushed, the product will be publish and active but after defined period it will be suspended (as per TT docs - https://developers.tiktok-shops.com/documents/document/240047) If we try to push a product for creation, without GTIN filled, error message should appear ( Error message: GTIN is required) | | | | type | | GTIN OR EAN OR UPC OR ISBN (input one of them to this field) | Yes | | If we have filled value in Product > Barcode, we will push type=GTIN If we have filled value in Product>EAN, we will push the type= EAN If we have filled value in Product>UPC, we will push type= UPC If we have filled value in Product>ISBN, we will push type= ISBN | | | inventory | | | | | | | | | | quantity | | The value should be non-negative numbers(include number 0) The upper limit of the available stock value set at a time is 999999 | Yes | Product Account > Quantity | | | | | warehouse_id | | string This field is a required field (because some sellers will have multiple warehouses, sellers can get warehouse ID from API GetproductDetail. You must fill in the warehouse when you modify SKU). | Yes | Location TikTok > Warehouse ID | We will have only 1 warehouse. TikTok does not allow more than 1 WH. Account Locations => Location => Location TikTok We should pick the first account location for example and from there reach the location and get the ID from Location TikTok table.

Location TikTok is a slave table of “Locations“ Note: If a client has 3 warehouses, but he would want to send sum of the stock, in Hemi we will have 3 locations per account, for which locations will have 3 different stock files, which will be updated in Location Quantities. Those 3 locations will be added into the Account Locations (will be summed by stock recalculation). Into Location TikTok we need to add the Warehouse ID which ID will be one ID for those 3 locations (TikTok does not allow us more than one WH ID) | | | price | | | | Yes | | | | | | amount | | | Yes | Product Account > Price | | | | | currency | | Currencies are different in different regions. The mapping relationship between region and currency is as follows: US: USD GB: GBP ID: IDR TH: THB MY: MYR PH: PHP VN: VND SG: SGD | Yes | Product Account > Currency OR Account > Exchange Rate Calculator Currency | Product Account is with priority

We should be able to send only the listed currencies. Any other currencies should return an internal error stating that the currency is incorrect. sales_attributes These are the "type": "SALES_PROPERTY" from the taxonomy id We can obtain the built-in sales attribute IDs through the GetAttributes API No Product Account > Item Specific OR Product Account > Variation Specific Id of the attribute // This will be item specific name name We can use custom sales attributes instead of using platform-provided sales attribute ids. If we do not specify a sales attribute ID and instead input a string to define a sales attribute (for example, inputting the name as "Battery Type"), the TT system will generate a new unique attribute ID for you. No Product Account > Item Specific OR Product Account > Variation Specific This will be item & variation specific value.
sku_img We can add an image to a sales attribute value, and the image will be displayed to the buyer. No <v1.3> (2) Main Image

from the TikTok Images using TikTok Image ID instead of url | We need to send only one image here. We want to have a logic and only send the Main image for the specific variant if we have attribute name which contains “Color” <v1.9> OR “Colour”</1.9>. If we don’t have attribute which contains Color we don’t send any image.


Example : If we are listing variant with color - Red, we want to send the Main Image for this exact variant.</v1.3> | | | | | uri | The image URI returned by the "Upload Image" API. If a product has variants that share more than one sales attribute, such as size and color, you can only choose one of the sales attribute to link an image. | No | N/A | | | | | value_id | | When creating a new sales attribute value, there is no need to input the value_id. After submitting the custom_value request, the seller will receive the value_id assigned by the platform (which can be viewed in the response body). | No | N/A | | | | | value_name | | When creating new sales attribute values, sellers are required to input custom sales attribute values. | No | Product Account > Item Specific Product Account > Variation Specific | | | | seller_sku | | | The external_sku_id is the sku identifier for the external system. It is used to associate it with the product sku. The input character length can not exceed 999. | No | Product > SKU | | | | sku_unit_count | | | The number of unit count of the SKU. The range is from 0.01 - 99999.99 | No | N/A | | | title | | | | The name of product.

  • For US and UK shops, the product name must have at least 1 character and no more than 255 characters.
  • For shops in other regions, the product name must have at least 25 characters and no more than 255 characters. | Yes | Product Account > Title | | | video | | | | | No | N/A | | | | id | | | | No | N/A | |

Note: We will have the same product ids, across all variants (same logic as eBay)

Example Response:

{
  "code": 0,
  "data": {
    "product_id": "1729592969712207008",
    "skus": [
      {
        "external_sku_id": "1729592969712207234",
        "id": "1729592969712207012",
        "sales_attributes": [
          {
            "id": "100000",
            "value_id": "1729592969712207123"
          }
        ],
        "seller_sku": "Color-Red-XM001"
      }
    ],
    "warnings": [
      {
        "message": "The [brand_id]:123 field is incorrect and has been automatically cleared by the system. Reason: [Brand does not exist]. You can edit it later."
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Response Mapping:

Integration Field Integration Notes Integration required Hemi Mapping Hemi Notes
code
data
product_id Yes Product Account > Channel item ID
skus
external_sku_id N/A
id Product Account TikTok > SKU ID Note: The value of this field & the value in field “Channel item ID“ are required when we perform updates as Update Price, Stock, etc.
sales_attributes
warningsid N/A
value_id N/A
seller_sku N/A
warnings N/A
message N/A
message N/A
request_id N/A

*Important:** We will not set the status to Product Published in Hemi, because we need to incorporate Get Product Details API call, which will compare the TikTok product statuses with Hemi statuses. The “GetProductDetails“ call is added in separate section below Create Products.

The successfull response will be with code : 0 and message : Success . If we receive a different code than 0, this means there was an error and we need to store the error. We want to store the error message as per the abstraction Product Listing general requirements :

Code​ Message​
12019011​ product package weight is invalid​
12052013​ The product description cannot exceed maximum characters​
12052015​ The product description is required​
12052023​ Category does not exist​
12052024​ Category is not final category​
12052026​ Brand does not exist​
12052028​ Main product image is required​
12052048​ You can't edit other sellers' products.​
12052051​ The product name exceed max limit characters​
12052055​ The SKU stock exceed limit.​
12052056​ The num of image in description cannot exceed max limit​
12052092​ product sale price is invalid​
12052093​ seller create product over limit​
12052104​ property is required​
12052105​ required qualification miss​
12052200​ brand is expired​
12052201​ brand does not comply with nice classification​
12052208​ A brand authorization is required to publish this listing.​
12052220​ The category status is unavailable.​
12052221​ Only whitelisted sellers are permitted to trade under current category​
12052222​ category do not support cod​
12052223​ the category is unauthorized.​
12052225​ This category status is not available because this category is not within the main category of the store. You do not have permission to use it for this purpose. Please contact AM to apply or re-select the category of the available status.​
12052226​ the category is unauthorized.​
12052227​ the category is unauthorized or unavailable​
12052240​ Do not support custom property.​
12052241​ attribute name or attribute id is empty.​
12052242​ The attribute name characters cannot exceed max_limit​
12052243​ The product attribute or sale attribute name characters contain Chinese.​
12052244​ The attribute name duplicate.​
12052245​ The product attributes contained invalid characters. Please modify and re-submit.​
12052246​ The attribute not support multi selected.​
12052251​ The attribute value name duplicate.​
12052254​ Duplicate attribute id​
12052260​ product id not exist​
12052261​ product name is empty​
12052262​ Chinese characters are not supported in product name​
12052300​ product main image uri illegal​
12052302​ The main images size exceed limit.​
12052304​ Main product image format not support.​
12052305​ The main images aspect ratio cannot exceed max limit.​
12052306​ main product images count exceed limit​
12052324​ Product description image file format is not supported​
12052340​ product description image uri illegal​
12052341​ The description images size cannot exceed limit.​
12052342​ The description images space cannot exceed limit.​
12052344​ The product description html syntax with error​
12052345​ The product description html tag not support.​
12052346​ The product description has Chinese characters​
12052348​ The product description html tag required attribute is miss.​
12052349​ The product description html tag not support nest.​
12052350​ The product description html tag contain illegal attribute.​
12052360​ The video id is not exist.​
12052520​ product sale property image uri illegal​
12052521​ The sale property images size over limit. ​
12052522​ Product sale property image is required​
12052523​ Product sale property image format not support.​
12052524​ The sale property image aspect ratio invalid​
12052525​ The attribute max num cannot exceed 3.​
12052527​ The sale attribute id not exist.​
12052528​ Just allow one sale property contain image.​
12052531​ warehouse status invalid​
12052532​ the warehouse not delivery warehouse​
12052560​ The SKU contains duplicate sales attribute.​
12052570​ product price exceed limit​
12052671​ The sizechart images size over limit.​
12052673​ Product sizechart image is required​
12052700​ seller is inactived​
12052701​ do not support cross-boarder seller create local product directly​
12052703​ Invalid seller tax number​
12052704​ seller id not exist​
12052900​ System error, try again later​

Get Product Detail

This call need to be incorporated, because we do not receive product status into the response for “Create Product“ call. In order to make sure we have successfully list a product on TikTok, we should use their statuses and map them to our internal statuses.

The cron should pick products with following statuses:

Product Status = Product Created/Product Published; List update the whole item = Sent

API Call: GET /product/202309/products/{product_id}

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

The {product_id} is what we have stored as Product Account > Channel Item ID

We need to pass the shop_cipher as query property which was obtained with the Get Authorised Shops call found here TikTok - Authentication & Database structure

From the example call below, we need to use only status

Еxample response:

{
  "code": 0,
  "data": {
    "audit_failed_reasons": [
      {
        "position": "product",
        "reasons": [
          "violate listing rules"
        ],
        "suggestions": [
          "The product violates TikTok Shopping listing rules, please check and resubmit."
        ]
      }
    ],
    "brand": {
      "id": "7082427311584347905",
      "name": "brand xxx aaa"
    },
    "category_chains": [
      {
        "id": "853000",
        "is_leaf": true,
        "local_name": "Botol & Stoples Penyimpanan",
        "parent_id": "851848"
      }
    ],
    "certifications": [
      {
        "files": [
          {
            "format": "PDF",
            "id": "v09ea0g40000cj91373c77u3mid3g1s0",
            "name": "CERT_X2.PDF",
            "urls": [
              "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
            ]
          }
        ],
        "id": "602362",
        "images": [
          {
            "height": 600,
            "thumb_urls": [
              "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
            ],
            "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe",
            "urls": [
              "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
            ],
            "width": 600
          }
        ],
        "title": "SNI Certificate"
      }
    ],
    "create_time": 1234567890,
    "delivery_options": [
      {
        "id": "1729592969712203232",
        "is_available": true,
        "name": "\"\""
      }
    ],
    "description": "<p>Please compare above detailed size with your measurement 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\" />\n",
    "external_product_id": "172959296971220002",
    "id": "1729592969712207008",
    "is_cod_allowed": true,
    "main_images": [
      {
        "height": 600,
        "thumb_urls": [
          "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
        ],
        "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe",
        "urls": [
          "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
        ],
        "width": 600
      }
    ],
    "manufacturer": {
      "address": "123W 106th St, New York, NY, USA, 10025",
      "email": "samplemanufacturer101@outlook.com",
      "name": "Sample Manufacturer Name",
      "phone_number": "12345678"
    },
    "package_dimensions": {
      "height": "10",
      "length": "10",
      "unit": "CENTIMETER",
      "width": "10"
    },
    "package_weight": {
      "unit": "KILOGRAM",
      "value": "1.32"
    },
    "product_attributes": [
      {
        "id": "100392",
        "name": "Occasion",
        "values": [
          {
            "id": "1001533",
            "name": "Birthday"
          }
        ]
      }
    ],
    "product_types": "COMBINED_PRODUCT",
    "size_chart": {
      "image": {
        "height": 600,
        "thumb_urls": [
          "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
        ],
        "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe",
        "urls": [
          "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
        ],
        "width": 600
      },
      "template": {
        "id": "7267563252536723205"
      }
    },
    "skus": [
      {
        "combined_skus": [
          {
            "product_id": "1729582718312380123",
            "sku_count": 1,
            "sku_id": "1729582718312380123"
          }
        ],
        "external_sku_id": "1729592969712207234",
        "global_listing_policy": {
          "inventory_type": "SHARED",
          "price_sync": true,
          "replicate_source": {
            "product_id": "1729592969712203232",
            "shop_id": "7295929697122032321",
            "sku_id": "1729592969712203232"
          }
        },
        "id": "10001",
        "identifier_code": {
          "code": "10000000000010",
          "type": "GTIN"
        },
        "inventory": [
          {
            "quantity": 999,
            "warehouse_id": "6966568648651605766"
          }
        ],
        "price": {
          "currency": "USD",
          "sale_price": "117.5",
          "tax_exclusive_price": "110",
          "unit_price": "1"
        },
        "sales_attributes": [
          {
            "id": "100000",
            "name": "Color",
            "sku_img": {
              "height": 100,
              "thumb_urls": [
                "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
              ],
              "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe",
              "urls": [
                "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
              ],
              "width": 100
            },
            "value_id": "100000",
            "value_name": "Red"
          }
        ],
        "seller_sku": "sku name",
        "sku_unit_count": "1.00"
      }
    ],
    "status": "SELLER_DEACTIVATED",
    "title": "Short Boat Invisible Socks",
    "update_time": 1234567899,
    "video": {
      "cover_url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036",
      "format": "MP4",
      "height": 480,
      "id": "v09ea0g40000cj91373c77u3mid3g1s0",
      "size": 1000,
      "url": "https://v16m-default.akamaized.net/bbae7099581b26cd340beaa7821b2d8c/64de6020/video/tos/alisg/tos-alisg-v-f466fc-sg/oMne9QuzIBN3fIDN7bFCCMbBKuGigg12ghDC8k/?a=0&ch=0&cr=0&dr=0&er=0&lr=default&cd=0%7C0%7C0%7C0&br=2212&bt=1106&cs=0&ds=3&ft=dl9~j-Inz7TKnfsfiyq8Z&mime_type=video_mp4&qs=13&rc=anR4Ojk6ZmYzbTMzODRmNEBpanR4Ojk6ZmYzbTMzODRmNEBsYWFwcjRva2NgLS1kLy1zYSNsYWFwcjRva2NgLS1kLy1zcw%3D%3D&l=202308171159498F7B108584E58B010932&btag=e00048000",
      "width": 1280
    }
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

We should incorporate a cron which will compare the statuses of the products in TikTok and based on their statuses, to set our internal statuses as follows:

TikTok Product Status Hemi Product / Listing Statuses Notes
DRAFT N/A
PENDING N/A
FAILED Listing status= Inactive Product Status = Product Created + List/Update the Whole item = Error TikTok updates 13/06/2022: Get Product API will return the reason as a new response data - reasons. When the value of response data - status is failed there will be the reason in this new response data.
ACTIVATE Listing status= Active Product Status = Product Published + List update the whole item = Not Needed + <v1.8> Product Account TikTok > TikTok Product Status = Activated </v1.8>
SELLER_DEACTIVATED Listing status= Inactive Product Status = Product Published + List update the whole item = Not Needed + List update the whole item = Not Needed + <v1.8> Product Account TikTok > TikTok Product Status = Deactivated </v1.8>
PLATFORM_DEACTIVATED Listing status= Inactive Product Status = Product Published + List/Update the Whole item = Error + <v1.8> Product Account TikTok > TikTok Product Status = Deactivated </v1.8> We will set this status if we receive status- PLATFORM_DEACTIVATED;
FREEZE Listing status= Inactive Product Status = Product Created + List/Update the Whole item = Error TBD We will handle such case as described in “Hemi Product/ Listing Statuses“ because TikTok does not provide detailed information regarding the Freeze status.
DELETED Listing status= Inactive Product Status = Product Removed + List/Update the Whole item = Error The error message which will be displayed “The product was deleted from the marketplace“

*Important Note:** Get Product Details cron should pick only variants with Channel Item IDs and SKU IDs!!!

Is this article helpful?
0 0 0