POST Search Products
Search Products Shop Required scope: seller.product.basic Retrieve a list of products that meet the specified conditions. This API will only return the key product properties. You can pass a returned product ID to the Get Product API
to obtain more details about the product. Version 202502
POST/product/202502/products/search
Request
Header
| Properties | Type | Description |
|---|---|---|
| content-type Required | string | Allowed type: application/json |
| x-tts-access-token Required | string | The seller access_token value from Get Access Token, when user_type = 0. Follow this guide to get seller access_token. |
Query
| Properties | Type | Description |
|---|---|---|
| app_key Required | string | Every single app will have a unique key. Please use the specific key assigned to your app. |
| sign Required | string | Signature generated by gen algorithm. When you send API requests to TTS, you must sign them so that TTS can identify the senders. |
| timestamp Required | int | Unix timestamp GMT (UTC+00:00). This timestamp is used across all API requests. Developers can use this convert to local time. |
| page_size Required | int | The number of results to be returned per page. Valid range: [1-100] |
| page_token | string | An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the next_page_token from a previous response. It is not needed for the first page. |
| shop_cipher Required | string | Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response. Get by API Get Authorization Shop |
Body
| Properties | Type | Description |
|---|---|---|
| status | string | Filter products based on the product's base version. In other words, this filter does not apply to post-live drafts or edits. For example, status=DRAFT returns only unpublished products in the DRAFT state, not live products with an active draft.Possible values: - ALL- DRAFT- PENDING- FAILED- ACTIVATE- SELLER_DEACTIVATED- PLATFORM_DEACTIVATED- FREEZE- DELETEDDefault: ALL |
| seller_skus | []string | Filter products by these seller SKU codes. |
| create_time_ge | int | Filter products to show only those that are created on or after the specified date and time. Unix timestamp.Note:create_time_ge and create_time_le together constitute the creation time filter condition.- If create_time_ge is filled but create_time_le is empty, create_time_le will default to the current time.- If create_time_le is filled but create_time_ge is empty, create_time_ge will default to the earliest shop time. |
| create_time_le | int | Filter products to show only those that are created on or before the specified date and time. Unix timestamp.Refer to notes in create_time_ge for more usage information. |
| update_time_ge | int | Filter products to show only those that are updated on or after the specified date and time. Unix timestamp.Note:update_time_ge and update_time_le together define the update time filter condition.- If update_time_ge is filled but update_time_le is empty, update_time_le will default to the current time.- If update_time_le is filled but update_time_ge is empty, update_time_ge will default to the earliest shop time. |
| update_time_le | int | Filter products to show only those that are updated on or before the specified date and time. Unix timestamp.Refer to notes in update_time_ge for more usage information. |
| category_version | string | Filter products by the category tree version.Possible values based on region:- US: v2, represents the 7-level category tree.- Other regions: v1, represents the 3-level category tree.Default: Return all products from both v1 and v2 category trees. |
| listing_quality_tiers | []string | Filter products by their listing quality tier.Possible values:- POOR- FAIR- GOODDefault: Returns allNote: Available only for the US market. |
| listing_platforms | []string | Filter products by the listing platforms.Possible values:- TOKOPEDIA- TIKTOK_SHOPDefault: Return all products regardless of their listing platform.Applicable only for sellers that migrated from Tokopedia.Note:- You must also specify a status value other than ALL when filtering by listing platforms. Returning all statuses is not supported.- If you pass in one platform, the search will return products that are listed on that platform, including those that are listed on both platforms.- If you pass in ["TIKTOK_SHOP", "TOKOPEDIA"], only products listed on both platforms will be returned, not those listed on just one. |
| audit_status | []string | Filter products by their audit status for TikTok Shop.Possible values: - AUDITING: Returns products where the base version or a post-live edit is currently being audited.- FAILED: Returns products where the base version or a post-live edit has failed audit, or had the audit cancelled.- APPROVED: Returns products that passed the audit and has been listed on the platform. |
| sku_ids | []string | Filter products by SKU IDs.Max count: 10 |
| sns_filter | string | Filter products by their Subscribe and Save (SNS) status. Possible values:- CONFIGURED- ELIGIBLE |
| return_draft_version | bool | Filter products to show only those that have a draft.- true: Returns products in their draft version only. Excludes those without a draft.- false: Returns all products regardless of whether they have a draft.Default: falseNote: Applicable only if the product status filter is ALL, DRAFT, ACTIVATE, SELLER_DEACTIVATED, or PLATFORM_DEACTIVATED. |
| locale | string | The BCP-47 locale codes for displaying category information.Default: The default locale of your shop.Possible values:- cs-CZ- de-AT- de-BE- de-DE- el-GR- en-GB- en-IE- en-US- es-ES- es-MX- fr-FR- fr-BE- hu-HU- id-ID- it-IT- ja-JP- ms-MY- nl-NL- nl-BE- pl-PL- pt-BR- pt-PT- th-TH- vi-VN- zh-CN |
Example
CurlGoNode.jsJavaEnable word wrap
Response Parameters
| Properties | Type | Description |
|---|---|---|
| code | int | The success or failure status code returned in API response. |
| message | string | The success or failure messages returned in API response. Reasons of failure will be described in the message. |
| request_id | string | Request log |
| data | object | Specific return information |
Example
JSONEnable word wrap
Error Code
View common error codes
| Code | Message | | --- | --- | | 12019027 | The maximum count of “seller_skus” in the search filter is 10. | | 12019087 | The number of SKU IDs exceeds the limit of 10 | | 12019108 | page number is invalid | | 12019109 | page size is invalid | | 12019118 | search create time invalid | | 12019119 | search update time invalid | | 12052180 | The total number of search results can not exceed 10000. | | 12052700 | The seller is inactive. | | 12052704 | seller id not exist | | 36009003 | Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support. | | 12052910 | Invalid input parameters. Refer to the API documentation for details. |
Is this content helpful?Helpful
Not Helpful
PreviousNext