Skip to content
TikTok Shop Partner API

Diagnose and Optimize Product

POST
/product/202411/products/diagnose_optimize

Diagnose products to obtain information that helps you to improve the product content, enhancing product visibility and customer trust. The returned information includes:

  • Listing quality information (available only for the US market).
  • Issues with the current product details and the overall recommendations
  • Auto-generated optimization suggestions targeted for specific product fields, including the title, description, and image. This API enables you to diagnose both live products (status: ACTIVATE) and brand-new products not yet listed in TikTok Shop.
  • To diagnose a live product, provide the product_id and category_id and leave all other product details blank.
  • To diagnose a brand-new product not yet listed in TikTok Shop, omit the product_id and provide the product details as necessary.
  • To diagnose a product similar to an existing one, provide the product_id and category_id, along with any new details. The diagnosis will combine the existing product’s information with the new details you provide. For example, if you provide a new title, the diagnosis will use the new title instead of the existing one while keeping the other values from the product ID. Note:
  • To diagnose multiple live products, use the Product Information Issue Diagnosis API.
  • This API focuses solely on optimizing product visibility and does not evaluate whether your product meets listing requirements. Quality issues identified by this API do not block your product from being listed. To verify listing requirements, use the Check Product Listing API.

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
product_id

The product ID of an existing product in TikTok Shop.

  • Omit this if you are diagnosing a brand-new product not yet listed in TikTok Shop.
  • Provide this ID if the product is similar to an existing one, and you want the diagnosis to consider both the existing product’s details and the new information in this request.
string
category_id
required

The ID of the category of this product. It must be a leaf category. Use the Get Categories API to find a leaf category. Note:

  • For the US market, refer to TikTok Shop Restricted Products Policy for information on product category restrictions.
  • For the Indonesia market, to list a product on both TikTok Shop and Tokopedia, you must use only categories that are available on both platforms.
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.
  • Images must use TikTok Shop image URLs, not exceed 4000px, and include 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
brand_id

The ID of the brand of this product. Use the Get Brands API to get the list of available brands for a shop. Note: Unauthorized brands won’t be displayed on TikTok Shop.

string
main_images

A list of images to display in the product image gallery. Use the Upload Product Image API to upload the images first and obtain the corresponding image URI. Note:

  • Max number of image URIs: 9
  • Arrange your image URIs in the sequence that they should appear on TikTok Shop.
  • Image dimensions: [300x300 px, 4000x4000 px] Recommendations:
  • Use a minimum of 5 images.
  • The first image should have a white background. Use the Optimize Images API to change the background to white.
Array<object>
object
uri

The URI of the image. Retrieve the URI from the Upload Product Image API or the Optimize Images API.

string
title

The product title. Title length:

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

A list of general attributes (e.g. manufacturer, country of origin, materials used) that describe the product as a whole, regardless of variant. Note: The attributes available for use are determined by the system based on the product’s assigned category, with some being mandatory. Retrieve the product attributes by using the Get Attributes API.

Array<object>
object
id

The ID of the product attribute, retrieved from the Get Attributes API.

string
values

A list of selectable values for the product attribute. Note: Provide either a built-in ID or a custom name; if both are provided, the ID takes priority.

Array<object>
object
id

The ID of a built-in product attribute value, retrieved from the Get Attributes API.

string
name

A self-defined custom product attribute value if the built-in values do not satisfy your needs. The system will auto-generate an ID after listing. Note:

  • No duplicates allowed under the same attribute.
  • Max length: 500 characters
string
<= 500 characters
size_chart

The measurement details of the product to help buyers find the right size. Note:

  • For certain product categories, size charts may be required or not supported. Use the Get Category Rules API to check the requirements.
  • Provide either a TikTok Shop size chart template ID or a size chart image; if both are provided, the ID takes priority.
object
template

A TikTok Shop size chart template generated by the size chart tool in Seller Center > Manage Products > Bulk action > Batch manage size charts.

object
id

The size chart template ID.

string
image

An image of the size chart.

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
optimization_fields

The fields for which you want to generate specific optimization suggestions. Possible values:

  • TITLE: Product title
  • DESCRIPTION: Product description (suggestions for this may take more than 10 seconds to generate)
  • IMAGE: Product image displayed in the image gallery
  • ALL: Suggestions are generated for all the above fields
  • NONE: No suggestions will be provided. Default: NONE
Array<string>
Allowed values: TITLE DESCRIPTION IMAGE ALL NONE
Example
{
  "product_id": "1729592969712203232",
  "category_id": "600001",
  "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' /> ",
  "brand_id": "7082427311584347905",
  "main_images": [
    {
      "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
    }
  ],
  "title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short Boat Invisible Socks",
  "product_attributes": [
    {
      "id": "100392",
      "values": [
        {
          "id": "1001533",
          "name": "Birthday"
        }
      ]
    }
  ],
  "size_chart": {
    "template": {
      "id": "7267563252536723205"
    },
    "image": {
      "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe\n"
    }
  },
  "optimization_fields": [
    "ALL"
  ]
}

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
listing_quality

Product listing quality information.

object
current_tier

The current quality tier of this product listing. The quality tier of a product listing depends on the quality of the content in its product fields such as the title, image, attributes etc.

Possible values:

  • POOR
  • FAIR
  • GOOD

NOTE: Available only for the US market.

string
Allowed values: POOR FAIR GOOD
remaining_recommendations

The remaining number of recommendations (see diagnosis_results) that must be implemented for the product to advance to the highest tier.

Note:

  • To advance to the highest tier, you must implement all recommendations listed in diagnosis_results.
  • Available only for the US market.
integer format: int64
diagnoses

Product diagnosis and optimization information.

Array<object>
object
field

The product field being diagnosed. Possible values:

  • TITLE: Product title
  • DESCRIPTION: Product description
  • IMAGE: Product image displayed in the image gallery
  • ATTRIBUTE: Product attribute
  • SIZE_CHART: Product size chart
string
Allowed values: TITLE DESCRIPTION IMAGE ATTRIBUTE SIZE_CHART
diagnosis_results

The results of diagnosing the specified field.

Array<object>
object
code

A machine-readable code that represents an identified issue. Refer to Listing quality diagnosis for the full list of identified issues and the corresponding recommendations.

string
how_to_solve

The recommendation for resolving the identified issue, returned in the default locale language of the shop. Refer to Listing quality diagnosis for the full list of recommendations.

string
quality_tier

The listing quality tier you can reach by implementing the recommendation. Possible values:

  • FAIR
  • GOOD

Note:

  • To reach a higher tier, you must implement all recommendations from the destination tier and all preceding tiers. For example, a product will reach the “GOOD” tier once all “FAIR” and “GOOD” recommendations are addressed or implemented.
  • Available only for the US market.
string
Allowed values: FAIR GOOD
suggestion

Optimization suggestions that are auto-generated by the system to improve the effectiveness of the specified field.

Note: This will not be returned if the value for optimization_fields is blank or NONE.

object
seo_words

The SEO keyword suggestions if diagnoses.field is “TITLE”.

Array<object>
object
text

The suggested SEO keyword text.

string
smart_texts

The intelligent text suggestions for titles and descriptions.

Array<object>
object
text

The suggested intelligent text.

string
images

The optimized main image. Only the first image in the main image set will be optimized.

Array<object>
object
height

The image height after optimization.

integer format: int64
width

The image width after optimization.

integer format: int64
uri

The original URI of the image.

string
url

The original URL of the image.

string
optimized_uri

The URI of the image after optimization.

string
optimized_url

The URL of the image after optimization.

string
Example
{
  "code": 0,
  "data": {
    "listing_quality": {
      "current_tier": "POOR",
      "remaining_recommendations": 3
    },
    "diagnoses": [
      {
        "field": "TITLE",
        "diagnosis_results": [
          {
            "code": "TITLE_LESS_THAN_40_CHARACTERS",
            "how_to_solve": "Names must be at least 40 characters long and contain product-identifying information, such as \"hiking boots\" or \"lipstick\".",
            "quality_tier": "FAIR"
          }
        ],
        "suggestion": {
          "seo_words": [
            {
              "text": "dress"
            }
          ],
          "smart_texts": [
            {
              "text": "this is a good title"
            }
          ],
          "images": [
            {
              "height": 600,
              "width": 600,
              "uri": "tos-maliva-i-o3syd03w52-us/53b55d6e8cdf1f315affa7e70b45707d",
              "url": "https://p16-graph-va.ibyteimg.com/tos-maliva-i-1por3rr4fy-us/v2/53b55d6e8cdf1f315affa7e70b45707d~tplv-1por3rr4fy-image.webp",
              "optimized_uri": "tos-maliva-i-o3syd03w52-us/0266127022264e54ad2f639f5e0fb5e6",
              "optimized_url": "https://p16-graph-va.ibyteimg.com/tos-maliva-i-1por3rr4fy-us/v2/0266127022264e54ad2f639f5e0fb5e6~tplv-1por3rr4fy-image.webp"
            }
          ]
        }
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec