TikTok Shop API & Scraper
The TikTok Shop API returns product, seller, category and review data from TikTok Shop across ten markets — the US, UK, Malaysia, Singapore, Thailand, the Philippines, Vietnam, Indonesia, Japan and Mexico — as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The US keyword search returns product_id, title, url, image, seller_id and seller_name, rating, review_count, sold_count, sku_count, price and list_price with currency, discount_percent and the promotional labels TikTok shows on the card. product_detail adds per-SKU price and stock, products_by_ids refreshes up to 15 US product ids in a single call, and category_tree with category_products walks the marketplace's own taxonomy. ranking_list, premium_offers and recommended_for_you expose the best-seller and deal feeds, seller_profile and seller_catalog cover a shop and its listings, related_products finds comparable items, and reviews returns customer feedback. It is built for social-commerce pricing, seller intelligence and trend tracking. One ReefAPI key, one shared credit pool, the standard envelope.
Id shapes, and the price fields that exist only on a promotion
Two things account for most of the surprises here. Every identifier is a long numeric string that must never be parsed as a number, and three of the price fields are populated only when the product is genuinely on promotion. They are not zeroed or nulled at random, they follow is_promotional. All values below came from measured calls on the US and Japanese storefronts.
| Field | Format | What was measured |
|---|---|---|
| product_id | 19-digit numeric string. The same value on every action. | 1729450858130215273. The identical id on the gb market returned NOT_FOUND, because a catalogue is per-market. |
| sku_id | 19-digit numeric string, one per variant. | That product carried 98 skus, each with its own available_quantity (13, 6 and 29 on the first three), summing to total_stock 1011. |
| seller_id and global_seller_id | 19-digit numeric strings, identical on the US shop measured. | 7495552880616442217, shop "WateLves Footwear", on_sell_product_count 38. |
| category_id | 6-digit numeric string. Three levels, and level 1 has parent_category_id "0". | 601352 Shoes, then 900616 Men's Shoes, then 601357 Casual Trainers with is_leaf true only on the last. |
| is_promotional | Boolean. It gates the two fields below. | true on one product and false on another inside the same bulk response. |
| list_price and discount_percent | Populated only when is_promotional is true, and null otherwise. | Promoted: price 32.99, list_price 42.99, discount_percent 23.0. Not promoted: price 84.97, list_price null, discount_percent null. |
| currency and currency_symbol | Set by market, not by your locale. | us returned USD with "$"; jp returned JPY with "円" and price 6113 as a whole number, since yen has no minor unit. |
| sold_count | An exact integer, not the banded string the storefront prints. | 52870 on a product whose page shows "52.9K sold". |
| review_time_ms | Unix milliseconds, 13 digits, not seconds. | 1754626324657 on a measured review. |
| not_found[] | Returned by products_by_ids only, and trustworthy there. | Three ids in, two products out, not_found ["1111111111111111111"], completeness_pct 66.67. |
price_prefix is a display hint, not a number. It came back "From" at the product level on a multi-SKU listing and null on each individual SKU, because the product-level price is the cheapest variant rather than one price for everything.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/tiktok-shop/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "yoga mat",
"max_results": 30
}
}{
"ok": true,
"meta": {
"api": "tiktok-shop",
"endpoint": "search",
"mode": "live",
"latency_ms": 3442.1,
"record_count": 30,
"bytes": 414455,
"cache_hit": false,
"completeness_pct": 100,
"stop_reason": "limit_reached",
"market": "us",
"pages": 1
},
"data": {
"results": [
{
"product_id": "[redacted-phone]",
"title": "Fitvids 1/2\" Thick High Density Exercise Yoga Mat, Carrying Strap, Pale Pink",
"url": "https://shop.tiktok.com/us/pdp/fitvids-1-2-thick-high-density-yoga-mat-non-slip-portable/[redacted-phone]",
"slug": "fitvids-1-2-thick-high-density-yoga-mat-non-slip-portable",
"image": "https://p16-oec-general-useast5.ttcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/f70024901f3649f98e2f8b9ae5a919d6~tplv-fhlh96nyum-crop-webp:2000:2000.webp?dr=12190&t=555f072d&ps=933b5bde&shp=8dbd94bf&shcp=a6e80448&idc=useast5&from=[redacted-phone]",
"brand": null,
"seller_id": "[redacted-phone]",
"seller_name": "Spreetail",
"rating": 4.7,
"review_count": 277,
"sold_count": 2805,
"sku_count": 7,
"labels": [
"Back to School",
"Free shipping"
],
"price": 18.99,
"list_price": 49.99,
"currency": "USD",
"currency_symbol": "$",
"discount_percent": 62,
"is_promotional": true,
"price_prefix": "From"
},
{
"product_id": "[redacted-phone]",
"title": "Yoga Mat 183x61cm Non Slip Exercise Mat for Pilates Workout, Extra Long Large Cushioned Fitness Mat for Women Men, High Density Anti Tear Gym Mat for Home Floor Stretching, Yoga Accessories for Beginner",
"url": "https://shop.tiktok.com/us/pdp/non-slip-yoga-mat-183x61cm-ideal-for-pilates-workouts/[redacted-phone]",
"slug": "non-slip-yoga-mat-183x61cm-ideal-for-pilates-workouts",
"image": "https://p16-oec-general.ttcdn-us.com/tos-maliva-i-o3syd03w52-us/f924653ae5674f118f5d6838c0df6314~tplv-fhlh96nyum-crop-webp:2048:2048.webp?dr=12190&t=555f072d&ps=933b5bde&shp=8dbd94bf&shcp=a6e80448&idc=useast5&from=[redacted-phone]",
"brand": null,
"seller_id": "[redacted-phone]",
"seller_name": "PeakPerformanceNow",
"rating": null,
"review_count": 0,
"sold_count": 15,
"sku_count": 5,
"labels": null,
"price": 19.95,
"list_price": 39.89,
"currency": "USD",
"currency_symbol": "$",
"discount_percent": 50,
"is_promotional": true,
"price_prefix": "From"
},
{
"product_id": "[redacted-phone]",
"title": "Extra-Thick 8mm Yoga Mat for Women&Men - Non-Slip Exercise MatHeavy Duty Workout Mat for Home Gym, Pilates & Floor Workouts,for 8 Fitness Ways: Yoga, Pilates, Gymnastics, Push-ups, Jumping Rope, Jumping Jacks, Plank, Squats Yoga Mat with Strap",
"url": "https://shop.tiktok.com/us/pdp/extra-thick-8mm-yoga-mat-for-men-women-non-slip-heavy-duty/[redacted-phone]",
"slug": "extra-thick-8mm-yoga-mat-for-men-women-non-slip-heavy-duty",
"image": "https://p16-oec-general-useast5.ttcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/4a6047fd671343c5a92bf4ba468f746e~tplv-fhlh96nyum-crop-webp:800:800.webp?dr=12190&t=555f072d&ps=933b5bde&shp=8dbd94bf&shcp=a6e80448&idc=useast5&from=[redacted-phone]",
"brand": null,
"seller_id": "[redacted-phone]",
"seller_name": "PeakPerformanceNow",
"rating": 4.1,
"review_count": 7,
"sold_count": 98,
"sku_count": 4,
"labels": [
"Back to School",
"Flash sale",
"Free shipping"
],
"price": 22.29,
"list_price": 46.89,
"currency": "USD",
"currency_symbol": "$",
"discount_percent": 52,
"is_promotional": true,
"price_prefix": "From"
}
],
"shops": [
{
"seller_id": "[redacted-phone]",
"shop_name": "Spreetail",
"shop_logo": "https://p19-oec-general-useast5.ttcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/185f19914ae34c7f8fc82eb5f6c7d7da~tplv-fhlh96nyum-resize-png:300:300.png?dr=12184&t=555f072d&ps=933b5bde&shp=905da467&shcp=d9d491bf&idc=useast5&from=[redacted-phone]",
"verified": true
},
{
"seller_id": "[redacted-phone]",
"shop_name": "bala",
"shop_logo": "https://p16-oec-general-useast5.ttcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/5ee46e970cc34a84a0af1ad705e11648~tplv-fhlh96nyum-resize-png:300:300.png?dr=12184&t=555f072d&ps=933b5bde&shp=905da467&shcp=d9d491bf&idc=useast5&from=[redacted-phone]",
"verified": true
},
{
"seller_id": "[redacted-phone]",
"shop_name": "QVC, Inc",
"shop_logo": "https://p16-oec-general-useast5.ttcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/4ae4940e7bcf436491ab2ddb3363ce9c~tplv-fhlh96nyum-resize-png:300:300.png?dr=12184&t=555f072d&ps=933b5bde&shp=905da467&shcp=d9d491bf&idc=useast5&from=[redacted-phone]",
"verified": true
}
],
"query": "yoga mat",
"has_more": true,
"pages_fetched": 1,
"requested_max": 30
}
}What the TikTok Shop API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| product_detail | Full TikTok Shop product record in ONE call, for any of the ten markets — title, structured description, every image, EVERY SKU with its own price and its exact remaining stock as an integer, shipping weight in grams and package size in centimetres, discount and list price, shipping fee and delivery window, category path, the seller's full profile, three customer reviews and the complete star histogram. Nothing here needs a second request | Pricing teams call product_detail to get full TikTok Shop product record in ONE call, for any of the ten markets. | product_id, market |
| products_by_ids | Look up as many as 15 US products in a SINGLE call — the cheapest way to refresh a list of ids you already hold, at roughly a sixth of the bandwidth per product of fetching each product page. It is also the only route on TikTok Shop with an unambiguous 'not found', which makes it the right way to check whether an id is still live before spending a full product fetch on it. US catalogue only | Marketplace operators call products_by_ids to look up as many as 15 US products in a SINGLE call. | product_ids |
| category_tree | TikTok Shop's own category taxonomy for any of the ten markets — 28 top-level departments from one call, then walk down to level 2 and level 3 by passing a category_id. Every node says whether it is a leaf, so the tree can be crawled to the bottom with no external id list and nothing hard-coded | Catalog enrichment teams call category_tree to get tikTok Shop's own category taxonomy for any of the ten markets. | market, category_id, slug |
| category_products | Browse a whole category and page through it — around 100 products per category, on ALL TEN markets. This is the cheapest source of product ids there is, roughly 1 KB of traffic per product, and it is what replaces keyword search outside the US. Pages are position-independent, so a page that gets throttled is retried automatically without losing your place | Retail analysts call category_products to get browse a whole category and page through it. | category_id, market, max_results, slug |
| search | Keyword search across the US TikTok Shop catalogue, paged for you up to 150 products, with price, rating, sold count and seller on every row. US ONLY — TikTok does not serve keyword search on any other market, at any URL (use category_products there, which goes deeper than search does) | Pricing teams call search to get keyword search across the US TikTok Shop catalogue, paged for you up to 150 products, with pr…. | query, max_results |
| recommended_shops | Shops TikTok itself surfaces for a search term — a keyword-to-seller lookup that answers 'who sells this' rather than 'what is for sale'. Comes free alongside the US search page, so it costs one call and no extra bandwidth. US only | Marketplace operators call recommended_shops to get shops TikTok itself surfaces for a search term. | query |
| seller_profile | A TikTok Shop seller's full public profile on any of the ten markets — shop name, rating, review count, follower count, lifetime units sold, catalogue size, video count and TikTok's own service sub-scores. On the nine non-US markets there is no seller endpoint at all, so this is reached through one of the seller's products; pass a product_id and you get the seller for free | Catalog enrichment teams call seller_profile to get a TikTok Shop seller's full public profile on any of the ten markets. | seller_id, product_id, market |
| seller_catalog | Every product a seller has listed, paged to the end — verified complete against the shop's own advertised product count (12 of 12, 81 of 81, 28 of 28 on three separate markets). Nine markets: US, Malaysia, Singapore, Thailand, Philippines, Vietnam, Indonesia, Japan and Mexico. NOT the UK, where TikTok does not deploy the seller catalogue service at all | Retail analysts call seller_catalog to get every product a seller has listed, paged to the end. | seller_id, market, max_results |
| related_products | The products TikTok itself recommends alongside a given product — its 'you may also like' rail, about 25 full product rows. Useful for competitor sets, substitutes and building a similar-items shelf. Works on all ten markets | Pricing teams call related_products to get the products TikTok itself recommends alongside a given product. | product_id, market, max_results |
| ranking_list | TikTok Shop's own best-seller board for the US — the 20 products TikTok is promoting as trending right now, in their published rank order, with full price, rating and seller rows. This is the editorial ranking the storefront shows, not a re-sorted search, which is what makes it the winning-products feed | Marketplace operators call ranking_list to get tikTok Shop's own best-seller board for the US. | none |
| premium_offers | TikTok Shop's US 'premium offers' deal board, paged to the end — around 97 discounted products with the discount percentage and the pre-discount price on every row. A ready-made deals feed rather than a price filter over search | Catalog enrichment teams call premium_offers to get tikTok Shop's US 'premium offers' deal board, paged to the end. | max_results |
| recommended_for_you | TikTok Shop's US personalised discovery feed, paged and de-duplicated — 200-plus distinct products of what TikTok is currently pushing to shoppers. The widest trend-discovery surface this API has | Retail analysts call recommended_for_you to get tikTok Shop's US personalised discovery feed, paged and de-duplicated. | max_results |
| reviews | Customer reviews for a product on any of the ten markets — three full review texts with rating, author, verified-purchase flag and photo, plus the COMPLETE 1-to-5 star histogram and total review count covering every review the product has. Served from a 7 KB endpoint instead of the product page, so a ratings refresh costs a fraction of a re-fetch | Pricing teams call reviews to get customer reviews for a product on any of the ten markets. | product_id, market |
Call search from your stack
curl -X POST https://api.reefapi.com/tiktok-shop/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"yoga mat","max_results":30}'import requests
r = requests.post(
"https://api.reefapi.com/tiktok-shop/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "yoga mat",
"max_results": 30
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/tiktok-shop/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "yoga mat",
"max_results": 30
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.tiktok-shop.search with {"query":"yoga mat","max_results":30}.Who uses this API and why
- Pricing teams call search then product_detail to track a product's per-SKU price and stock against its list price.
- Trend and merchandising tools use ranking_list and premium_offers to see what is selling and what is discounted right now.
- Seller-intelligence products use seller_profile and seller_catalog to audit a competitor's whole TikTok Shop inventory.
- Catalogue pipelines use products_by_ids to refresh 15 products per call instead of one request per id.
Questions developers ask before integrating
list_price and discount_percent are null on some products. Is data missing?
No. Read is_promotional first. Those two fields are populated when and only when the product is genuinely on promotion. In one measured bulk call a promoted product returned price 32.99, list_price 42.99 and discount_percent 23.0, while a second product in the same response returned price 84.97 with both other fields null and is_promotional false. There is no hidden pre-discount price on a product that is not discounted, so a null here means "not on sale", not "failed to parse".
How do I check whether a product id is still live without paying for a full fetch?
Use products_by_ids. It takes up to 15 US ids in one call and returns a not_found[] array you can trust. A measured call with two real ids and one made-up id returned two products, not_found ["1111111111111111111"], requested 3, returned 2 and completeness_pct 66.67. It gives you the listing card only, with no skus[], no per-SKU stock, no description and no reviews, so use it to validate and price a list and then spend a product_detail call on the ids that matter.
The same product id works on us but not on gb. Why?
Because market selects the storefront and the catalogue, not merely the currency. A measured product_detail for 1729450858130215273 on market=us returned the full record, while the identical id on market=gb returned NOT_FOUND with a message saying the product does not exist in the gb catalogue, confirmed on two independent observations. Sellers list per market, so treat the pair (product_id, market) as your key rather than the id on its own.
Is sold_count exact, or is it the rounded number from the page?
Exact. A measured product returned sold_count 52870 while its storefront page prints "52.9K sold", and the seller record returned sold_count 186348 against a shop blurb reading "186.3K sold". You get the underlying integer rather than the banded display string, which is the difference between being able to compute a weekly delta and not. review_count behaves the same way, returning 6227 rather than "6.2K".
How does per-SKU stock work, and does it add up?
Yes, and that is the point of it. skus[] carries available_quantity as a real integer per variant, alongside in_stock, properties[] (colour, size and so on), and its own price and package dimensions. A measured 98-SKU shoe listing had 13, 6 and 29 units on its first three variants and reported total_stock 1011 for the product, and total_stock is the sum. That lets you watch a single size run out instead of only seeing the whole product flip to unavailable.
How does the review histogram relate to average_rating?
review_summary is complete even though the review texts are not. A measured product returned rating_distribution with numeric string keys, {"1":149, "2":56, "3":144, "4":451, "5":5427}, summing exactly to total_reviews 6227, and the weighted mean of that distribution is 4.759, which is the average_rating 4.8 it reported. So you can recompute the rating, chart its shape, or track how the one-star bucket moves, all from a 7 KB call rather than re-fetching the product page.
Why do I only get three review texts?
Three is what the public review surface serves per product, and we ship what we can actually deliver rather than a number we cannot. Each of the three is a full record: review_id, rating, text, author, sku_id (so you know which variant was bought), verified_purchase, incentivized, and a photo where there is one. Note the author names arrive partially masked by TikTok itself, as "S**s" and "F**h C**l" in a measured response. For coverage of every review, read review_summary, which is complete.
Are category names localized for non-US markets?
Not reliably, so do not key on name. A measured category_tree on market=jp returned its 28 top-level departments with name in English, "Womenswear & Underwear" and "Phones & Electronics", identical to the US labels and carrying the same category_ids, 601152 and 601739. name_en holds the stable slug form, "womenswear-underwear". Key on category_id or name_en and use name for display only, because it is TikTok's own label and it varies by market.
What timestamp unit do reviews use?
Milliseconds. review_time_ms measured 1754626324657, which is 13 digits, and feeding that to a seconds-based parser puts the review roughly 53,000 years in the future. Divide by 1000 for anything expecting unix seconds. It is the only timestamp field on this API, so there is nothing to stay consistent with; just read the _ms suffix as the contract it is.
What is the TikTok Shop API?
TikTok Shop API is a ReefAPI endpoint group for products, per-sku stock, sellers, reviews and best-sellers across 10 markets. It returns live JSON through POST requests under /tiktok-shop/v1.
Is the TikTok Shop API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. TikTok Shop calls use the same shared credit balance as every other ReefAPI engine.
Do I need a TikTok Shop login or account?
No login to TikTok Shop is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the TikTok Shop data?
The page example is captured from a live product_detail call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the TikTok Shop API use?
TikTok Shop actions currently cost 1-2 credits per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.