# TikTok Product List API ## API Information - **API Name**: Get TikTok Shop Product List - **Request Method**: POST - **API URL**: `/open-api/v1/data` - **Interface URI path**: `/v3/api/open/tiktok-shop/product/list` - **Description**: Get TikTok shop product 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/product/list" | Yes | | | params | object | Interface parameter object | See parameter list below | Yes | | #### Parameter List (params object) | Parameter Name | Type | Description | Example | Required | Default | | --------------------- | ------- |-----------------------------------------------------------------------------------------------------------------------------------| ----------------- | -------- | ------- | | current_page | integer | Current page number, pagination query current page, starting from 1 | 1 | Yes | | | page_size | integer | Page size, number of records per page for pagination query, default 20 | 20 | Yes | | | sort | integer | Sort field, 1-Last time, 2-First time, 3-Sold, 4-GMV, 5-Impressions, 6-Ad Spend, 7-Ads, 8-influencers | 3 | Yes | | | sort_type | string | Sort type, asc-ascending, desc-descending | "desc" | Yes | | | time | long | Time range, 0-all, 1-yesterday,7-last 7 days, 30-last 30 days, 90-last 90 days | 30 | Yes | | | categorize | string | Category, multiple separated by commas, used to filter products by category | "cat_001,cat_002" | No | | | commission_rate_max | double | Maximum commission rate, used to filter products with commission rate not exceeding specified value | 0.2 | No | | | commission_rate_min | double | Minimum commission rate, used to filter products with commission rate not below specified value | 0.05 | No | | | cpm_max | double | Ad Spend, Maximum ad cost (CPM), used to filter products with ad cost not exceeding specified value | 10.0 | No | | | cpm_min | double | Ad Spend, Minimum ad cost (CPM), used to filter products with ad cost not below specified value | 1.0 | No | | | delivery | string | Delivery method, overseas-cross-border delivery, local-local delivery | "local" | No | | | found_time_end | long | First Ad date, End time of first ad discovery (timestamp), used to filter products first discovered within specified time range | 1643673600 | No | | | found_time_start | long | First Ad date, Start time of first ad discovery (timestamp), used to filter products first discovered within specified time range | 1640995200 | No | | | gmv_max | double | Maximum sales volume (GMV), used to filter products with sales volume not exceeding specified value | 100000.0 | No | | | gmv_min | double | Minimum sales volume (GMV), used to filter products with sales volume not below specified value | 1000.0 | No | | | is_in_marketplace | boolean | Whether it's a marketplace product, false-not marketplace product, true-marketplace product | true | No | | | is_managed | boolean | Whether it's a fully managed product, false-not fully managed product, true-fully managed product | false | No | | | keyword | string | Search keyword, used for fuzzy search by product title, description, etc. | "phone case" | No | | | last_found_time_end | long | Last Ad date, End time of last ad discovery (timestamp), used to filter products last discovered within specified time range | 1643673600 | No | | | last_found_time_start | long | Last Ad date, Start time of last ad discovery (timestamp), used to filter products last discovered within specified time range | 1640995200 | No | | | person_count_max | long | Influencers, Maximum number of influencers, used to filter products with influencer count not exceeding specified value | 100 | No | | | person_count_min | long | Influencers, Minimum number of influencers, used to filter products with influencer count not below specified value | 1 | No | | | play_count_max | long | Ad Impressions, Maximum play count/ad impressions, used to filter products with play count not exceeding specified value | 1000000 | No | | | play_count_min | long | Ad Impressions, Minimum play count/ad impressions, used to filter products with play count not below specified value | 1000 | No | | | price_usd_max | double | Price (USD), Maximum product price in USD, used to filter products with USD price not exceeding specified value | 100.0 | No | | | price_usd_min | double | Price (USD), Minimum product price in USD, used to filter products with USD price not below specified value | 10.0 | No | | | region | string | Country/region, multiple separated by commas, used to filter products by region | "US,GB" | No | | | sales_trend | integer | Sales trend, 1-Increase, 0-Stable, -1-Decrease | 1 | No | | | sales_volume_max | long | GMV, Maximum sales volume, used to filter products with sales volume not exceeding specified value | 10000 | No | | | sales_volume_min | long | GMV, Minimum sales volume, used to filter products with sales volume not below specified value | 100 | No | | | search_type | string | Search type, 1-product name description, 2-store name, 3-influencer name, default 1 | "1" | No | | | shop_id | string | Shop ID, used to filter products from specified shop | "shop_001" | No | | | video_count_max | long | Ads, Maximum ad count, used to filter products with ad count not exceeding specified value | 100 | No | | | video_count_min | long | Ads, Minimum ad count, used to filter products with ad count not below specified value | 1 | No | | #### Request Example ```bash 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/product/list", "params": { "current_page": 1, "page_size": 20, "sort": 3, "sort_type": "desc", "time": 30, "keyword": "phone case", "region": "US,GB", "price_usd_min": 10.0, "price_usd_max": 50.0, "sales_volume_min": 100 } }' ``` ### Response #### Response Body Structure ```json { "code": 200, "message": "success", "data": { "data": [ // Product list ], "page": { // Pagination information } }, "version": "v1", "timestamp": null, "sign": null, "remaining_credits": 9980, "consumed_credits": 20, "success": true, "fail": false } ``` #### Response Field Description ##### Main Response Fields | Field Name | Type | Description | | ------------- | ------- | ---------------------------------- | | **code** | Integer | Response status code | | **message** | String | Response message | | **data** | Object | Response data object | | **version** | String | API version number | | **timestamp** | Long | Timestamp (can be null) | | **sign** | String | Signature (can be null) | | **remaining_credits** | number | Current remaining available credits after this request | | **consumed_credits** | number | Credits consumed by this request | | **success** | Boolean | Whether the request was successful | | **fail** | Boolean | Whether the request failed | ##### Product Information Fields (list) | Field Name | Type | Description | | -------------------- | ------- | --------------------------------------------------------------------- | | id | string | Product unique identifier ID | | image | string | Product main image URL | | title | string | Product title | | desc | string | Product description (optional field) | | price | double | Product price (local currency) | | price_usd | double | Product price in USD | | sales_volume | long | Product sales volume | | score | double | Product rating | | shop_name | string | Shop name | | video_count | long | Number of ad videos | | categorize | object | Product category information | | region | string | Product target region | | 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 | | root_path | string | Product root path (domain) | | keywords | array | Product keyword list (optional field) | | card_found_time | long | Card first discovery time (timestamp) | | card_last_found_time | long | Card last discovery time (timestamp) | | commission_rate | double | Commission rate | | sales_trend | integer | Sales trend, 1-growth, 0-stable, -1-decline | | sales_trend_data | array | Sales trend data list | | gmv | double | Sales volume (GMV) | | delivery | string | Delivery method, overseas-cross-border delivery, local-local delivery | | is_in_marketplace | boolean | Whether it's a marketplace product | | is_managed | boolean | Whether it's a fully managed product | | person_count | long | Number of influencers | | shop_sales_volume | long | Shop sales volume | | gmv_usd | double | Sales volume in USD (GMV USD) | ##### Product Category Information Object Fields (categorize) | Field Name | Type | Description | | ---------- | ------ | ------------------------ | | \_id | string | Category ID | | name_zh | string | Chinese category name | | name_vi | string | Vietnamese category name | | name_th | string | Thai category name | | name_pt | string | Portuguese category name | | name_ja | string | Japanese category name | | name_id | string | Indonesian category name | | name_en | string | English category name | ##### Sales Trend Data Fields (sales_trend_data) | Field Name | Type | Description | | ------------ | ---- | ------------------ | | day | Long | Date timestamp | | sales_volume | Long | Daily 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 ```json { "code": 200, "message": "success", "data": { "data": [ { "id": "1731082690126648263", "image": "https://im.pipispy.com/products/images/4b5f6645b62f59e6.png", "title": "Scrub Daddy 10-Piece Multi-Color Microfiber Towel Set Colorful Cleaning", "price": 16.98, "price_usd": 16.98, "sales_volume": 2954, "score": 4.9, "shop_name": "QVC, Inc", "video_count": 30, "categorize": { "_id": "600409", "name_zh": "清洁抹布", "name_vi": "Khăn lau", "name_th": "ผ้าเช็ดทำความสะอาด", "name_pt": "Cleaning Cloths", "name_ja": "Cleaning Cloths", "name_id": "Kain Pembersih", "name_en": "Cleaning Cloths" }, "region": "US", "play_count": 3604387, "share_count": 1095, "found_time": 1748325472, "last_found_time": 1752200041, "insert_time": 1747783755, "update_time": 1752200071, "min_cpm": 12327.0, "max_cpm": 49416.15, "currency": "USD", "shop_id": "7495811038271212487", "is_collection": false, "shop_image": "https://im.pipispy.com/shops/images/63f695e743c88654.png", "root_path": "shop.tiktok.com", "card_found_time": 1748325472, "card_last_found_time": 1752200041, "commission_rate": 0.0, "sales_trend": 1, "sales_trend_data": [ { "day": 1748188800, "sales_volume": 139 }, { "day": 1748275200, "sales_volume": 1 } ], "gmv": 50158.92, "delivery": "local", "is_in_marketplace": false, "is_managed": true, "person_count": 20, "shop_sales_volume": 559338, "gmv_usd": 50158.92 } ], "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 Codes | Error Code | Description | | ---------- | ------------------------------------- | | 200 | Success | | 400 | Bad Request - Request parameter error | | 500 | Internal Server Error |