Skip to content
TikTok Shop Partner API

List Opportunities

POST
/product/202604/opportunities/query

Search and retrieve a paginated list of opportunity leads available to the authorized seller, with optional filters by type, status, category, etc and ordered by the algorithm ranking model.

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.

page_size
required
integer format: int64
<= 100

Number of results per page. Max: 100. Default: 20.

page_token
string

Pagination token from previous response. Omit for first page.

locale
string

The locale for localized category names, tags, and reward information, expressed as a BCP-47 language-country code, for example en-US. If omitted, the primary locale for the seller’s shop region is used.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
opportunity_type
required

The type of opportunity. Possible values:

  • PRODUCT: Product opportunity
  • KEYWORD: Search keyword opportunity
  • CATEGORY: Category opportunity
string
Allowed values: PRODUCT KEYWORD CATEGORY
category_ids

Filter by category IDs. Leave empty to return all leads that available to the seller.

Array<string>
create_time_ge

Filter opportunities created at or after this time. Provide a Unix timestamp in seconds (UTC).

integer format: int64
create_time_lt

Filter opportunities created before this time. timestamp in seconds

integer format: int64
tag_codes

A list of tag codes used to filter the results. You can provide at most 20 values. Use lowercase tag codes. The core_product and top_product tag codes are supported only when opportunity_type is PRODUCT; their availability also depends on the seller and market configuration.

Array<string>
Example
{
  "opportunity_type": "PRODUCT",
  "category_ids": [
    "601310",
    "601311"
  ],
  "create_time_ge": 1775976752,
  "create_time_lt": 1776976752,
  "tag_codes": [
    "core_product",
    "top_product"
  ]
}

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
data

Paginated opportunity results.

object
opportunities

The opportunities returned on the current page.

Array<object>
object
id

Unique ID of the opportunity

string
title

Opportunity title.

string
reference_images

Reference product images of the product to list.

Array<string>
category_id_level_1

TikTok Shop L1 category ID.

string
category_id_level_2

TikTok Shop L2 category ID.

string
category_id_level_3

TikTok Shop L3 category ID.

string
category_name_level_1

Category name of 1st level category.

string
category_name_level_2

Category name of 2nd level category.

string
category_name_level_3

Category name of 3rd level category.

string
is_collected

Whether the authorized seller has saved this opportunity to their collection.

boolean
query_words

Comma-separated TikTok Shop in-site search keywords associated with the opportunity.

string
opportunity_type

Type of opportunity: PRODUCT（品线索）/ KEYWORD（词线索）/ CATEGORY（类目线索） Empty return for a specific opportunity type indicates the business team has not enabled merchant submission for this lead type in the corresponding market.

string
brand_name

The brand name for products specified by the opportunity.

string
create_time

The opportunity creation time as a Unix timestamp in seconds (UTC).

integer format: int64
expire_time

Opportunity expiry date, second-level timestamp

integer format: int64
est_market_sales_volume

Estimated market sales volume for the last 30 days, returned as an approximate bucket: <100, a value rounded down to a hundreds bucket ending in 00+, a k+ or M+ value, or 100M+.

string
est_market_gmv

Estimated market sales GMV in USD for the last 30 days, returned as an approximate bucket: <100, a value rounded down to a hundreds bucket ending in 00+, a k+ or M+ value, or 100M+.

string
search_volume

TikTok Shop in-site search volume, rounded to the nearest whole number and returned as a decimal string.

string
competitor_product_count

Approximate number of competing products listed in the last 30 days, returned as one of < 10, < 50, < 100, or 100+.

string
video_view_pv

The cumulative short video view count of all videos associated with this product opportunity.

string
tags

Comma-separated display values for the opportunity tags. Each value is localized when a translation is available; otherwise, the configured tag description or tag code is returned.

string
tag_codes

Tag codes for the opportunity. The available codes depend on seller and market configuration. Examples for Latam include core_product and top_product.

Array<string>
reward_info

Comma-separated descriptions of rewards that sellers can gain by listing products as required. Values are localized when a translation is available; otherwise, the configured reward description is returned.

string
external_product_id

Product ID on the reference source.

string
reference_source

The reference platform code, returned only when external_product_id is present. Possible values:

  • 1: SHOPEE
  • 2: AMAZON
  • 3: LOOKFANTASTIC
  • 4: WALMART
  • 5: TTS
  • 6: ASOS
  • 7: UNIVERSAL_PRODUCT
  • 8: DTCNEXUS
  • 9: TEMU
  • 10: SHOPIFY
  • 11: NEXUS_SHOPIFY
  • 12: SHEIN
  • 13: PIXEL
  • 14: SHOPIFY_NON_1P
  • 15: MIRAVIA
  • 16: RAKUTEN
  • 17: EBAY
  • 18: ONBUY
  • 19: MERCADO_LIBRE
  • 20: ALLEGRO
  • 21: BOL
  • 22: DTC
string
Allowed values: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
next_page_token

Pagination token to pass as page_token in the next request. This field is omitted when there are no more results.

string
total_count

Total number of matching opportunities (approximate).

integer format: int64
Example
{
  "code": 0,
  "data": {
    "data": {
      "opportunities": [
        {
          "id": "7123456789012345678",
          "title": "title info",
          "reference_images": [
            "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/61e605ce483f4f7b9b419d510f74fd22~tplv-o3syd03w52-resize-image:400:400.image?dr=15586&t=555f072d&ps=933b5bde&shp=5563f2fb&shcp=122e87b3&idc=maliva&from=1432613627&from_p=305039283"
          ],
          "category_id_level_1": "901128",
          "category_id_level_2": "30122212",
          "category_id_level_3": "3321212",
          "category_name_level_1": "Shoes",
          "category_name_level_2": "Women's Shoes",
          "category_name_level_3": "Sandals & Flip Flops",
          "is_collected": false,
          "query_words": "word1,word2",
          "opportunity_type": "PRODUCT",
          "brand_name": "brand1",
          "create_time": 1712544000,
          "expire_time": 1712544000,
          "est_market_sales_volume": "100k+",
          "est_market_gmv": "9M+",
          "search_volume": "3312",
          "competitor_product_count": "100+",
          "video_view_pv": "7k+",
          "tags": "Pencarian teratas,Pencarian trending,Persaingan rendah,Trending di TikTok,Terlaris",
          "tag_codes": [
            "core_product"
          ],
          "reward_info": "Boost shoptab visibility",
          "external_product_id": "SH1234567890",
          "reference_source": "1"
        }
      ],
      "next_page_token": "100",
      "total_count": 200
    }
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec