POST Search Returns
Search Returns Shop Required scope: seller.return_refund.basic Use this API to search returns by return ID, order ID, buyer, return type, return status, arbitration status, or create/update time window. The response is paginated. To retrieve the next page, pass the previous next_page_token as page_token and keep all other filters and sorting unchanged. Version 202602
POST/return_refund/202602/returns/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. |
| sort_field | string | The returned results will be sorted by the specified field. Default: create_timePossible values:- create_time- update_timeSpecify the order for sorting the returned results by using the sort_order parameter. |
| sort_order | string | The sort order for the sort_field parameter. Default: ASCPossible values:- ASC: Ascending order- DESC: Descending order |
| page_size | string | The number of results to be returned per page. Default: 10. Valid range: [10-50]. |
| 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 |
|---|---|---|
| return_ids | []string | List of return IDs. |
| order_ids | []string | List of TikTok Shop order IDs. |
| buyer_user_ids | []string | List of TikTok Shop buyer user IDs. |
| return_types | []string | List of return types.Available values:- REFUND- RETURN_AND_REFUND- REPLACEMENT |
| return_status | []string | List of return status.Available values:- RETURN_OR_REFUND_REQUEST_PENDING: Buyer has initiated a return or refund request. The request is pending review by seller or system. - REFUND_OR_RETURN_REQUEST_REJECT: The return or refund request was rejected. - AWAITING_BUYER_SHIP: The return request was approved. The seller is waiting for the buyer to ship the approved items to the seller. If the buyer doesn't ship the items to the seller before the deadline, the platform will close the request.- BUYER_SHIPPED_ITEM: Buyer has shipped the approved items to seller.- REJECT_RECEIVE_PACKAGE: Seller inspected the returned items and rejected the return request. - RETURN_OR_REFUND_REQUEST_SUCCESS: The return/refund request was successful. The buyer will be refunded.- RETURN_OR_REFUND_REQUEST_CANCEL: The request has been cancelled by the buyer or system.- RETURN_OR_REFUND_REQUEST_COMPLETE: The return/refund was processed successfully. The buyer has been refunded.- REPLACEMENT_REQUEST_PENDING: Buyer has initiated a replacement request. The request is pending review by seller.- REPLACEMENT_REQUEST_REJECT: Seller reject the buyer replacement request.- REPLACEMENT_REQUEST_REFUND_SUCCESS: Buyer's replacement request was resolved by refund due to insufficient inventory.- REPLACEMENT_REQUEST_CANCEL: Buyer canceled the replacement request.- REPLACEMENT_REQUEST_COMPLETE: Seller has approved the buyer's replacement request, platform will generate a new order for seller to fulfill.- AWAITING_BUYER_RESPONSE: Seller offer another return type to the buyer, and waiting buyer response. Seller proposed return type can check the seller_proposed_return_type. |
| seller_proposed_return_type | []string | List of seller proposed return types.Available values:- PARTIAL_REFUND |
| create_time_ge | int | Filter returns 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_lt is filled but create_time_ge is empty, create_time_ge will default to the earliest shop time. |
| arbitration_status | []string | List of arbitration statuses. Available values:- IN_PROGRESS: The TikTok Shop platform operator is processing arbitration. Platform may request additional information from the seller. - SUPPORT_BUYER: The platform operator supports buyer.- SUPPORT_SELLER: The platform operator supports seller.- CLOSED: Arbitration is closed. |
| update_time_ge | int | Filter returns 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_lt is filled but update_time_ge is empty, update_time_ge will default to the earliest shop time. |
| update_time_lt | int | Filter returns to show only those that are created before the specified date and time. Unix timestamp.Refer to notes in create_time_ge for more usage information. |
| locale | string | The BCP-47 locale codes for displaying the returns, delimited by commas. Default: enRefer to Locale codes for the list of supported locale codes. |
| create_time_lt | int | Filter returns to show only those that are created before the specified date and time. Unix timestamp.Refer to notes in create_time_ge for more usage information. |
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 | | --- | --- | | 25001001 | An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format. | | 25020005 | No permission to process this order | | 36009003 | Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support. |
Is this content helpful?Helpful
Not Helpful
PreviousNext