TikTok Shop List API
- API Name: Get TikTok Shop Store List
- Request Method: POST
- API URL:
/open-api/v1/data
- Interface URI path:
/v3/api/open/tiktok-shop/shop/list
- Description: Get TikTok shop store list information based on filter conditions
- Pricing: Retrieving one data result consumes 1 credit
Request Headers:
- Content-Type: application/json
- Accept: application/json
Request Parameters
Request Structure
| Parameter Name |
Type |
Description |
Example |
Required |
Default |
| key |
string |
User's external API request key |
"your_api_key_here" |
Yes |
|
| uri |
string |
Interface URI path |
"/v3/api/open/tiktok-shop/shop/list" |
Yes |
|
| params |
object |
Interface parameter object |
See parameter list below |
Yes |
|
Request Body Parameters (params object)
| Parameter Name |
Type |
Required |
Description |
| avg_price_usd_max |
Double |
No |
Average Price(USD), Maximum average product price in USD, used to filter shops with average USD price not exceeding specified value |
| avg_price_usd_min |
Double |
No |
Average Price(USD), Minimum average product price in USD, used to filter shops with average USD price not below specified value |
| categorize |
String |
No |
Category, Third-level category ID, used to filter shops by category |
| cpm_max |
Double |
No |
Maximum ad cost (CPM), used to filter shops with ad cost not exceeding specified value |
| cpm_min |
Double |
No |
Minimum ad cost (CPM), used to filter shops with ad cost not below specified value |
| current_page |
Integer |
No |
Current page number, pagination query current page, starting from 1 |
| delivery |
String |
No |
Delivery method, overseas-cross-border delivery, local-local delivery |
| found_time_end |
Long |
No |
End time of first ad discovery (timestamp), used to filter shops first discovered within specified time range |
| found_time_start |
Long |
No |
Start time of first ad discovery (timestamp), used to filter shops first discovered within specified time range |
| gmv_max |
Double |
No |
GMV, Maximum sales volume (GMV), used to filter shops with sales volume not exceeding specified value |
| gmv_min |
Double |
No |
GMV, Minimum sales volume (GMV), used to filter shops with sales volume not below specified value |
| goods_count_max |
Long |
No |
Number of Products, Maximum number of goods, used to filter shops with goods count not exceeding specified value |
| goods_count_min |
Long |
No |
Number of Products, Minimum number of goods, used to filter shops with goods count not below specified value |
| is_managed |
Boolean |
No |
Whether it's a fully managed shop, false-not fully managed shop, true-fully managed shop |
| keyword |
String |
No |
Search keyword, used for fuzzy search by shop name, description, etc. |
| last_found_time_end |
Long |
No |
End time of last ad discovery (timestamp), used to filter shops last discovered within specified time range |
| last_found_time_start |
Long |
No |
Start time of last ad discovery (timestamp), used to filter shops last discovered within specified time range |
| page_size |
Integer |
No |
Page size, number of records per page for pagination query |
| person_count_max |
Long |
No |
Influencers, Maximum number of influencers, used to filter shops with influencer count not exceeding specified value |
| person_count_min |
Long |
No |
Influencers, Minimum number of influencers, used to filter shops with influencer count not below specified value |
| play_count_max |
Long |
No |
Ad Impressions, Maximum play count/ad impressions, used to filter shops with play count not exceeding specified value |
| play_count_min |
Long |
No |
Ad Impressions, Minimum play count/ad impressions, used to filter shops with play count not below specified value |
| product_type |
String |
No |
Product type, brand-brand, retail-retailer |
| region |
String |
No |
Country/region, used to filter shops by region |
| sales_trend |
Integer |
No |
Sales trend, 1-Increase, 0-Stable, -1-Decrease |
| sales_volume_max |
Long |
No |
Sold, Maximum sales volume, used to filter shops with sales volume not exceeding specified value |
| sales_volume_min |
Long |
No |
Sold, Minimum sales volume, used to filter shops with sales volume not below specified value |
| sort |
Integer |
No |
Sort field, 1-last ad time, 2-first ad time, 3-sold, 4-GMV, 5-impression, 6-ad spend, 7-ads, 8-influencers, 9-Number of Products, 10-Average Price |
| sort_type |
String |
No |
Sort type, asc-ascending, desc-descending |
| time |
Long |
No |
Time range, 0-all, 1-yesterday, 7-last 7 days, 30-last 30 days, 90-last 90 days |
| video_count_max |
Long |
No |
Maximum ad count, used to filter shops with ad count not exceeding specified value |
| video_count_min |
Long |
No |
Minimum ad count, used to filter shops with ad count not below specified value |
Request Example
curl -X POST "https://www.pipispy.com/open-api/v1/data" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"key": "your_api_key_here",
"uri": "/v3/api/open/tiktok-shop/shop/list",
"params": {
"current_page": 1,
"page_size": 20,
"sort": 3,
"sort_type": "desc",
"time": 30,
"keyword": "fashion accessories",
"region": "US",
"avg_price_usd_min": 10.0,
"avg_price_usd_max": 100.0,
"sales_volume_min": 1000,
"product_type": "brand"
}
}'
Response Parameters
Response Body Structure
{
"code": 200,
"message": "success",
"data": {
"data": [],
"page": {}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 20,
"success": true,
"fail": false
}
Response Field Description
| Field Name |
Type |
Description |
| code |
Integer |
Response status code, 200 indicates success |
| message |
String |
Response message |
| data |
Object |
Response data |
| data.data |
Array |
Shop list |
| data.page |
Object |
Pagination information |
| version |
String |
API version |
| timestamp |
Long |
Response timestamp (null in this case) |
| sign |
String |
Response signature (null in this case) |
| remaining_credits |
Long |
Current remaining available credits after this request |
| consumed_credits |
Long |
Credits consumed by this request |
| success |
Boolean |
Whether the request was successful |
| fail |
Boolean |
Whether the request failed |
| Field Name |
Type |
Description |
| id |
String |
Shop unique identifier ID |
| image |
String |
Shop main image URL |
| title |
String |
Shop title |
| sales_volume |
Long |
Shop sales volume |
| score |
Double |
Shop rating |
| shop_name |
String |
Shop name |
| video_count |
Long |
Number of ad videos |
| categorize |
Array |
Shop category information list (third-level categories) |
| region |
Array |
Shop target region list |
| play_count |
Long |
Play count/ad impressions |
| share_count |
Long |
Share count |
| found_time |
Long |
First discovery time (timestamp) |
| last_found_time |
Long |
Last discovery time (timestamp) |
| insert_time |
Long |
Data insertion time (timestamp) |
| update_time |
Long |
Data update time (timestamp) |
| min_cpm |
Double |
Minimum ad cost (CPM) |
| max_cpm |
Double |
Maximum ad cost (CPM) |
| currency |
String |
Currency type |
| shop_id |
String |
Shop ID |
| is_collection |
Boolean |
Whether it's collected |
| shop_image |
String |
Shop image URL |
| sales_trend |
Integer |
Sales trend, 1-growth, 0-stable, -1-decline |
| sales_trend_data |
Array |
Sales trend data list |
| gmv |
Double |
Sales volume (GMV) |
| is_in_marketplace |
Boolean |
Whether it's a marketplace shop |
| is_managed |
Boolean |
Whether it's a fully managed shop |
| person_count |
Long |
Number of influencers |
| gmv_usd |
Double |
Sales volume in USD (GMV USD) |
| goods_count |
Long |
Number of goods |
| goods_ad_count |
String |
Number of ad goods |
| best_selling_goods |
Array |
Best-selling goods list |
| avg_price |
Double |
Average price (local currency) |
| avg_price_usd |
Double |
Average price in USD |
| product_type |
Array |
Product type list, brand-Brand, retail-Retailer |
| delivery |
Array |
Shop Type, method list, overseas-Cross-border Shop, local-Local shop |
| Field Name |
Type |
Description |
| _id |
String |
Category ID |
| name_zh |
String |
Category name in Chinese |
| name_vi |
String |
Category name in Vietnamese |
| name_th |
String |
Category name in Thai |
| name_pt |
String |
Category name in Portuguese |
| name_ja |
String |
Category name in Japanese |
| name_id |
String |
Category name in Indonesian |
| name_en |
String |
Category name in English |
Sales Trend Data Fields (sales_trend_data array)
| Field Name |
Type |
Description |
| day |
Long |
Date timestamp |
| sales_volume |
Long |
Sales volume for that day |
Best Selling Goods Fields (best_selling_goods array)
| Field Name |
Type |
Description |
| product_id |
String |
Product ID |
| image |
String |
Product image URL |
| sales_volume |
Long |
Product sales volume |
Page Object Fields (page)
| Field Name |
Type |
Description |
| total_count |
Long |
Total number of records |
| page_count |
Long |
Total number of pages |
| current_page |
Long |
Current page number |
| page_size |
Long |
Page size |
| is_next |
Boolean |
Whether there is next page |
Response Example
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"id": "7495432992748505937",
"image": "https://im.pipispy.com/shops/images/5ecdf34a797edc74.png",
"title": "ZOOONE NATURE",
"sales_volume": 484186,
"score": 4.3,
"shop_name": "ZOOONE NATURE",
"video_count": 3157,
"categorize": [
{
"_id": "700650",
"name_zh": "保健食品",
"name_vi": "Thực phẩm bổ sung sức khỏe",
"name_th": "อาหารเสริมเพื่อสุขภาพ",
"name_pt": "Vitamins, Minerals & Wellness Supplements",
"name_ja": "Vitamins, Minerals & Wellness Supplements",
"name_id": "Suplemen Kesehatan",
"name_en": "Vitamins, Minerals & Wellness Supplements"
}
],
"region": ["US"],
"play_count": 203301212,
"share_count": 254734,
"found_time": 1701638465,
"last_found_time": 1752199606,
"insert_time": 1702748197,
"update_time": 1752199633,
"min_cpm": 695290.15,
"max_cpm": 2787259.62,
"currency": "USD",
"shop_id": "7495432992748505937",
"is_collection": false,
"shop_image": "https://im.pipispy.com/shops/images/5ecdf34a797edc74.png",
"sales_trend": -1,
"sales_trend_data": [
{
"day": 1744300800,
"sales_volume": 3565
}
],
"gmv": 12908398.76,
"is_in_marketplace": true,
"is_managed": true,
"person_count": 280,
"gmv_usd": 12908398.76,
"goods_count": 24,
"goods_ad_count": "25",
"best_selling_goods": [
{
"product_id": "1730501450773467985",
"image": "https://im.pipispy.com/products/images/9f33b35307396d27.png",
"sales_volume": 190407
}
],
"avg_price": 26.66,
"avg_price_usd": 26.66,
"product_type": ["brand", "retail"],
"delivery": ["local"]
}
],
"page": {
"total_count": 10000,
"page_count": 500,
"current_page": 1,
"page_size": 20,
"is_next": true
}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 20,
"success": true,
"fail": false
}
Error Code Description
| Error Code |
Description |
| 200 |
Success |
| 400 |
Request parameter error |
| 500 |
Server internal error |