stable本次发布有变化全部展示
来自 TikTok Shop 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Path: /return_refund/202602/returns
#§2 Method: [POST]
#§3 Function Description
Use this API to create a seller-initiated aftersales request for an order on behalf of the buyer. Supported request types are REFUND and RETURN_AND_REFUND. Before submitting the request, confirm that the order is eligible for the selected aftersales type and return method. After the request is created, use the relevant search, status, or review API to continue the aftersales workflow.
§4 Common Parameters
For common parameters, refer to How to call TikTok Shop APIs - Common Parameters
| Properties | Location | Type | Require | Sample | Properties description |
|---|---|---|---|---|---|
| shop_cipher | query | string | Y | GCP_XF90igAAAABh00qsWgtvOiGFNqyubMt3 | 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 | |||||
| content-type | header | string | Y | application/json | Allowed type: application/json |
§5 Request Query Parameters
| Properties | Type | Require | Sample | Properties description |
|---|---|---|---|---|
| app_key | string | N | 38abcd | Every single app will have a unique key. Please use the specific key assigned to your app. |
| sign | string | N | 5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c | Signature generated by gen algorithm. When you send API requests to TTS, you must sign them so that TTS can identify the senders. |
| timestamp | int | N | 1623812664 | Unix timestamp GMT (UTC+00:00). This timestamp is used across all API requests. Developers can use this convert to local time. |
| idempotency_key | string | N | 1623812664 | Idempotency Key |
§6 Request Body Parameters
| Properties | Type | Require | Sample | Properties description |
|---|---|---|---|---|
| order_id | string | Y | 576473917261320779 | Tiktok Shop order id |
| skus | []object | N | Skus | |
| ^sku_id | string | Y | 1729386416015578024 | Sku id seller wants to create a return request |
| ^quantity | int | Y | 1 | Quantity seller wants to create a return request |
| order_line_item_ids | []string | N | ["455764739172614518516"] | Specifies the order line IDs to include in the return request. If the order has been split into multiple packages, use order line IDs to create the return request. If neither order_line_item_ids nor skus is provided, the default is all order lines in the order. Note: This is a legacy field for new integrations use order_line_list instead. |
| return_reason | string | Y | ecom_order_delivered_refund_reason_missing_product_seller | Seller's reason to create a return |
| return_type | string | Y | REFUND | Which type to create: |
- REFUND
- RETURN_AND_REFUND | refund_total |string |N |10.5 |Total refund amount to the buyer. The total refund amount can not exceed the refundable amount | currency |string |N |USD |Currency for refund which should be same as currency in TikTok Ship Order. | shipment_type |string |N |PLATFORM |Specifies the return shipping method the buyer uses to send items back to the seller in a return request. Supported values:
PLATFORMBUYER_ARRANGE| handover_method |string |N |DROP_OFF |Optional. Only applicable when shipment_type isPLATFORM. Specifies the handover method the buyer uses to return the item through platform-supported shipping. Supported values:DROP_OFFPICKUP| order_line_list |[]object |N | |Specifies the line items to include in the return request and supports bundle order splitting. In one request, use eitherorder_line_item_idfor normal order lines orsub_order_line_item_idfor bundle sub-items. Note: This field is completely backward compatible with the previousorder_line_items_idsfield. | ^order_line_item_id |string |N |576469648086306986 |The corresponding order line ID | ^sub_order_line_item_id |string |N |576469648086306987 |The sub-order-line ID inside a bundle product- Required for bundle products
- Not required for non-bundle products |
§7 Request Sample
Query
https://open-api.tiktokglobalshop.com/return_refund/202602/returns?app_key=123abc&sign=5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c×tamp=1625484268&shop_cipher=ROW_RHkDDABBAAB8tKAVoAqsMTjsQZFLyNfY&idempotency_key=1623812664
Body
{"order_id":"576473917261320779","skus":[{"sku_id":"1729386416015578024","quantity":1}],"order_line_item_ids":["455764739172614518516"],"return_reason":"ecom_order_delivered_refund_reason_missing_product_seller","return_type":"REFUND","refund_total":"10.5","currency":"USD","shipment_type":"PLATFORM","handover_method":"DROP_OFF","order_line_list":[{"order_line_item_id":"576469648086306986","sub_order_line_item_id":"576469648086306987"}]}
§8 Response Parameters
| Properties | Type | Sample | Properties description |
|---|---|---|---|
| code | int | 0 | The success or failure status code returned in API response. |
| message | string | Success | The success or failure messages returned in API response. Reasons of failure will be described in the message. |
| request_id | string | 202203070749000101890810281E8C70B7 | Request log |
| data | object | Specific return information | |
| ^return_id | string | 4035319218955782461 | The identifier of a specific return request. |
| ^return_status | string | RETURN_OR_REFUND_REQUEST_PENDING | Return status, available values: |
- RETURN_OR_REFUND_REQUEST_PENDING: Request is pending, needs to be approved by seller or platform
- REFUND_OR_RETURN_REQUEST_REJECT: Seller rejected the request
- AWAITING_BUYER_SHIP: Waiting buyer to ship items to seller, if exceed the deadline, request will be closed by platform
- BUYER_SHIPPED_ITEM: Buyer has shipped items to seller.
- REJECT_RECEIVE_PACKAGE: Seller reject return package
- RETURN_OR_REFUND_REQUEST_SUCCESS: The refund/return request is successful, buyer will be refunded.
- RETURN_OR_REFUND_REQUEST_CANCEL: The request has been cancelled by buyer or system
- RETURN_OR_REFUND_REQUEST_COMPLETE: The request is successful, and the amount has been refunded. |
§9 Response Sample
{"code":0,"data":{"return_id":"4035319218955782461","return_status":"RETURN_OR_REFUND_REQUEST_PENDING"},"message":"Success","request_id":"202203070749000101890810281E8C70B7"}
§10 Error Code
For common error codes, refer to How to call TikTok Shop APIs - Common Error Code
| Code | Message |
|---|---|
| 25001001 | An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format. |
| 25001003 | Invalid order status. |
| 25001010 | A return request has already been completed, or the order has already been cancelled. |
| 25001011 | A return request is already in process, or the order has already been cancelled. |
| 25001014 | Unknown return reason. Please ensure you are passing a valid return reason. |
| 25001015 | The provided return reason cannot be used by the seller. Please select a valid return reason and try again. |
| 25001020 | The provided return reason is currently offline. Please select a different return reason. |
| 25001021 | Reason not match order status |
| 25001028 | reverse lock failed |
| 25001042 | Return package creation has failed due to internal error. |
| 25001046 | Return request has failed due to an interception by TikTok risk control. |
| 25001051 | Not allowed to return or cancel since order is completed or cancelled |
| 25005005 | Refund total amount is larger than the refundable amount. |
| 25005010 | Unable to cancel individual line items within this request. |
| 25005011 | The requested line item(s) for return or refund exceeds the allowable limit. |
| 25020005 | No permission to process this order |
| 36009003 | Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support. |