Skip to content
TikTok Shop Partner API

Get Opportunity Detail

GET
/product/202604/opportunities/{opportunity_id}

Retrieve the full details of a single opportunity lead by its ID, including market trend data, competition level, and recommended actions.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
opportunity_id
required
string

The unique ID of the opportunity lead generated by TikTok Shop.

Query Parameters

Section titled “Query Parameters”
shop_cipher
required
string

Identifies the shop. Obtain it from the Get Authorized Shops API.

locale
string

The locale used for localized opportunity content, expressed as {language_code}-{COUNTRY_CODE} in accordance with BCP 47. If omitted, the API uses the first configured locale for the authenticated shop’s region.

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
opportunity

Detailed opportunity information, including basic details, market and content data, listing criteria, and the recommended action.

object
id

Unique ID of the opportunity

string
action_type

The recommended action. Possible values:

  • LIST_SAME: List the same product.
  • LIST_SIMILAR: List a similar product.
string
Allowed values: LIST_SAME LIST_SIMILAR
listing_criteria

The criteria for products that match the opportunity lead.

object
product_brand

Requirement for product brand.

string
product_category

Requirement for product category.

string
product_status

Requirement for product status : LIVE / DRAFT

string
keywords

A comma-separated list of keywords that must be included in the product’s title, attributes, description, or other applicable content.

string
content_data

The relevant data for the past 30 days.

object
video_view_pv

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

string
shoppable_video_search_pv

The search page-view count for shoppable short videos associated with this product opportunity over the previous 30 days, returned as an approximate bucket: <100, a rounded-down hundreds value such as 300+, a rounded-down thousands value such as 12k+, a rounded-down millions value such as 1M+, or 100M+.

string
trending_hashtag

The top 1 video hashtag of the product-related videos, sorted by view count.

string
top_shoppable_video_links

Links to the top 10 shoppable short videos related to the product, sorted by view count.

Array<string>
market_data

The relevant data for the past 30 days.

object
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
market_buzz

Popularity level of the product: HOT / HIGH / MEDIUM

string
search_volume

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

string
search_keyword

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

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
competitor_seller_count

Number of competing sellers with the products currently listed.

string
basic_info

The detailed information of the opportunity.

object
opportunity_type

The opportunity type. Possible values:

  • PRODUCT: A product opportunity.
  • KEYWORD: A keyword opportunity.
  • CATEGORY: A category opportunity.
string
Allowed values: PRODUCT KEYWORD CATEGORY
status

Opportunity status: ACTIVE / EXPIRED / FULFILLED(已提报)

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
title

Opportunity title.

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
reference_price

The reference price for the product to list, formatted with the applicable currency symbol and three decimal places. If both price boundaries are available, the value is returned as a range; if one is available, a single price is returned; if neither is available, an empty string is returned.

string
reference_images

Reference product images of the product to list.

Array<string>
brand_info

Brand requirements for products specified by the opportunity.

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
recom_info

Recommendation reason why this is an 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>
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
Example
{
  "code": 0,
  "data": {
    "opportunity": {
      "id": "7123456789012345678",
      "action_type": "LIST_SAME",
      "listing_criteria": {
        "product_brand": "brand1",
        "product_category": "Phones & Electronics > Gaming & Consoles > Console Accessories",
        "product_status": "LIVE",
        "keywords": "word1,word2"
      },
      "content_data": {
        "video_view_pv": "7k+",
        "shoppable_video_search_pv": "336k+",
        "trending_hashtag": "tag1,tag2",
        "top_shoppable_video_links": [
          "https://www.tiktok.com/@/video/v15044gf0000d4l7p57og65m3s0tqfa0",
          "https://www.tiktok.com/@/video/v15044gf0000d306lrnog65h1a6283ug"
        ]
      },
      "market_data": {
        "est_market_sales_volume": "100k+",
        "est_market_gmv": "9M+",
        "market_buzz": "HOT",
        "search_volume": "100000",
        "search_keyword": "holiday",
        "competitor_product_count": "100+",
        "competitor_seller_count": "35"
      },
      "basic_info": {
        "opportunity_type": "PRODUCT",
        "status": "ACTIVE",
        "create_time": 1775973876,
        "expire_time": 1775973876,
        "title": "title",
        "category_id_level_1": "901128",
        "category_id_level_2": "30122212",
        "category_id_level_3": "40122212",
        "category_name_level_1": "Shoes",
        "category_name_level_2": "Women's Shoes",
        "category_name_level_3": "Sandals & Flip Flops",
        "reference_price": "$36.300 - $38.500",
        "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"
        ],
        "brand_info": "some brand info",
        "reward_info": "Boost shoptab visibility",
        "recom_info": "Trending, but out of stock",
        "tags": "Pencarian teratas,Pencarian trending,Persaingan rendah,Trending di TikTok,Terlaris",
        "tag_codes": [
          "core_product"
        ],
        "external_product_id": "SH1234567890",
        "reference_source": "1"
      }
    }
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec