TikTok Shop API — filters & query parameters
This reference is for integrators calling /api/v1/tiktok-shop/* with an API key, or the same path shapes under /api/tiktok-shop/... in a logged-in browser session. HTTP route list and high-level behavior: API reference.
How parameters are sent#
| Mechanism |
Details |
| Query string |
Usual for GET. |
| POST JSON |
For explore and count routes that accept POST, a JSON object in the body is merged with query parameters (same keys as the tables below). Use this when filter sets are large (avoids 414 URI Too Long). |
| Form POST |
application/x-www-form-urlencoded body is also merged into params. |
| Omitted / empty |
Empty string, null, or the literal string "undefined" are stripped and usually ignored. |
Explore & count (categories, shops, creators, videos, products)#
These map to:
Route suffix (under /api/v1/tiktok-shop/) |
Purpose |
categories/explore, categories/count |
List or filter categories / count matches |
shops/explore, shops/count |
List or search shops / count matches |
creators/explore, creators/count |
List or search creators / count matches |
videos/explore, videos/count |
List or search videos / count matches |
products/explore, products/count |
List or search products / count matches |
Pagination & sorting (explore only; not sent on count)
| Parameter |
Default |
Notes |
page |
1 |
Integer page. |
limit |
20 |
Page size. |
after |
— |
Opaque keyset cursor (forward pagination). |
include_total |
— |
If present, forwarded to upstream. |
checkpoint_jump |
— |
If present, forwarded to upstream. |
sort |
See default_sort per entity below |
Upstream maps period-specific sort fields. |
order |
desc |
Sort direction. |
Category scoping (explore & count, when has_category_hierarchy is true)#
| Parameter |
Notes |
category_ids |
Comma-separated or array; merged with level IDs below. |
category_l1_id, category_l2_id, category_l3_id |
Single ID; plural aliases category_l1_ids, category_l2_ids, category_l3_ids also accepted. |
exclude_category_ids |
Comma-separated list to exclude. |
Defaults#
| Parameter |
Default |
country |
US |
Entity-specific filters#
Each entity exposes an allowlisted set of filters. Requests use canonical parameter names; aliases accept alternate names (same value).
Categories — default_sort: revenue_origin#
| Filters |
country, level, category_ids, name, period, min_revenue, max_revenue, min_revenue_per_shop, max_revenue_per_shop, min_top_3_shop_ratio, max_top_3_shop_ratio, min_top_10_shop_ratio, max_top_10_shop_ratio, min_shop_count, max_shop_count, min_video_count, max_video_count |
Aliases: min_revenue ← min_revenue_30_days; max_revenue ← max_revenue_30_days.
Shops — default_sort: revenue#
| Filters |
country, name, period, category_ids, min_revenue, max_revenue, min_revenue_growth_rate, max_revenue_growth_rate, min_sales_growth_rate, max_sales_growth_rate, first_seen, min_rating, max_rating, seller_type, min_product_count, max_product_count, min_avg_unit_price, max_avg_unit_price, min_creator_count, max_creator_count, min_video_count, max_video_count, min_channel_strategy_self_operated_percentage, max_channel_strategy_self_operated_percentage |
Aliases: min_revenue ← min_gmv_30d; max_revenue ← max_gmv_30d; min_revenue_growth_rate ← min_gmv_growth_rate_30d; max_revenue_growth_rate ← max_gmv_growth_rate_30d; min_avg_unit_price ← min_avg_price; max_avg_unit_price ← max_avg_price.
Creators — default_sort: revenue#
| Filters |
country, name, period, category_ids, min_revenue, max_revenue, min_revenue_growth_rate, max_revenue_growth_rate, min_followers_growth_rate, max_followers_growth_rate, min_views_growth_rate, max_views_growth_rate, min_followers, max_followers, min_views, max_views, verified, min_product_count, max_product_count, min_video_count, max_video_count |
Aliases: min_revenue ← min_gmv_30d; max_revenue ← max_gmv_30d.
Videos — default_sort: revenue#
| Filters |
country, name, period, category_ids, min_revenue, max_revenue, min_revenue_growth_rate, max_revenue_growth_rate, min_views_growth_rate, max_views_growth_rate, min_likes_growth_rate, max_likes_growth_rate, min_shares_growth_rate, max_shares_growth_rate, min_views, max_views, min_duration, max_duration, min_roas, max_roas, min_ad_spend, max_ad_spend, min_likes, max_likes, min_creator_followers, max_creator_followers, publish_date, is_ad, is_affiliate, is_self_promotion, is_ai_ugc, revenue_trend |
Products — default_sort: revenue#
| Filters |
country, name, period, category_ids, min_revenue, max_revenue, min_revenue_growth_rate, max_revenue_growth_rate, min_sales_growth_rate, max_sales_growth_rate, min_item_sold, max_item_sold, min_sold_count, max_sold_count, min_avg_unit_price, max_avg_unit_price, min_commission_rate, max_commission_rate, min_product_score, max_product_score, min_product_review_cnt, max_product_review_cnt, min_creator_count, max_creator_count, min_product_launch_date, max_product_launch_date, min_creator_conversion_ratio, max_creator_conversion_ratio, first_seen, min_price, max_price |
Aliases: min_item_sold ← min_sold; max_item_sold ← max_sold.
Allowed sort values#
Sort keys are not fully enumerated in this doc; the upstream analytics service maps generic sort keys to period-specific fields. Treat sort as an opaque string aligned with the web app’s filter UI, or inspect network calls from the dashboard for the same entity.
Dashboard-only parameters#
Do not rely on undocumented dashboard query flags for metering. For API integrations, send only the filters documented above and follow Credits & billing.
GET /api/v1/tiktok-shop/products#
Query parameters (all optional except auth):
| Parameter |
Default |
page |
0 |
limit |
20 |
sort |
sales_desc |
category, min_price, max_price, min_sales, max_sales, min_rating, date_from, date_to, search, country |
— |
GET /api/v1/tiktok-shop/search (searchProducts)#
| Parameter |
Required |
q |
Yes (search string) |
page |
No (0 default) |
limit |
No (20 default) |
category |
Geen |
GET /api/v1/tiktok-shop/trending (getTrendingProducts)#
| Parameter |
Default |
limit |
10 |
timeframe |
7days |
category |
— |
GET /api/v1/tiktok-shop/shop-details / shops/details (getShopDetails)#
| Parameter |
Required |
id |
Yes — shop identifier |
GET /api/v1/tiktok-shop/suggestions (suggestions)#
| Parameter |
Required |
Notes |
type |
Ja |
One of: categories, shops, creators, products, videos. |
q |
Ja |
Partial name; empty returns empty suggestions. |
limit |
Geen |
1–20, default 10. |
country |
Geen |
Default US. |
Hierarchy & static reads#
| Path |
Parameters |
categories/hierarchy, categories/layers |
country (default US). |
categories/summary, categories/history, … |
Mostly GET query params (country, ids, period, …); see the in-app network tab for the exact shape per route. |
For POST bodies on detail routes (shop-detail, product-detail, etc.), each route has its own JSON shape — capture a request from the dashboard for the tab you need, then replay it against /api/v1/tiktok-shop/... with your API key.
MCP tools (same data as explore)#
If you use Model Context Protocol (Claude Desktop, etc.), the TikTok tools issue the same explore/count payloads the HTTP API accepts — same filter semantics as this document where applicable (keyword, country, page, size vs HTTP limit, revenue/price bounds on products, …).
| MCP tool |
Maps to |
search_tiktok_products |
products/explore |
search_tiktok_shops |
shops/explore |
search_tiktok_creators |
creators/explore |
search_tiktok_videos |
videos/explore |
count_tiktok_entities |
Counts results matching the same filters used in the explore endpoints. |
browse_tiktok_categories, list_tiktok_category_top, autocomplete_tiktok |
Category hierarchy / layers / summary / history / siblings / top lists / suggestions |
get_tiktok_product, get_tiktok_shop, get_tiktok_creator, get_tiktok_video |
Detail + slice payloads (metrics, history, lists, strategy) — see MCP tools reference |
get_tiktok_trending_products |
Same idea as GET /api/v1/tiktok-shop/trending (section below) |
check_credits |
Same idea as GET /api/v1/tiktok-shop/credits |
Full argument names: MCP · tools reference.
Where to look next#
| Concern |
Locatie |
| Route list (paths + verbs) |
API reference — TikTok Shop section |
| Filters & bodies (this doc) |
Tables above |
| Entity details (JSON bodies) |
TikTok Shop details |
| ce](/docs/api) — TikTok Shop section |
|
| Filters & bodies (this doc) |
Tables above + in-app network captures for edge cases |
