Search Returns

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.

---

For common parameters, refer to How to call TikTok Shop APIs - Common Parameters

• create_time
• update_time

Specify the order for sorting the returned results by using the sort_order parameter. | sort_order |string |N |ASC |The sort order for the sort_field parameter. Default: ASC Possible values:

• ASC: Ascending order
• DESC: Descending order | page_size |string |N |10 |The number of results to be returned per page. Default: 10. Valid range: [10-50]. | page_token |string |N |aDU2dHIzMlFhME5CUzJKUDhDdVJhTDM1WmJkeFVTVW9LTkRaSnNaZCtuWjJXVU5CSDhlaA== |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. |

• REFUND
• RETURN_AND_REFUND
• REPLACEMENT
• EXCHANGE | return_status |[]string |N |["RETURN_OR_REFUND_REQUEST_PENDING"] |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.
• EXCHANGE_REQUEST_PENDING: Buyer has initiated an exchange request. The request is pending review by seller.
• EXCHANGE_REQUEST_REFUND_SUCCESS: Buyer's exchange request was resolved by refund due to insufficient inventory.
• EXCHANGE_REQUEST_CANCEL: Buyer canceled the exchange request.
• EXCHANGE_REQUEST_COMPLETE: Seller has approved the buyer's exchange request, platform will generate a new order for seller to fulfill. | seller_proposed_return_type |[]string |N |["PARTIAL_REFUND"] |List of seller proposed return types. Available values:
• PARTIAL_REFUND | create_time_ge |int |N |1690340825 |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 |N |["IN_PROGRESS"] |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 |N |1690340825 |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 |N |1690340825 |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 |N |en-US |The BCP-47 locale codes for displaying the returns, delimited by commas. Default: en Refer to Locale codes for the list of supported locale codes. | create_time_lt |int |N |1690340825 |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. |

Query

https://open-api.tiktokglobalshop.com/return_refund/202602/returns/search?app_key=123abc&sign=5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c&timestamp=1625484268&shop_cipher=ROW_RHkDDABBAAB8tKAVoAqsMTjsQZFLyNfY&sort_field=create_time&sort_order=ASC&page_size=10&page_token=aDU2dHIzMlFhME5CUzJKUDhDdVJhTDM1WmJkeFVTVW9LTkRaSnNaZCtuWjJXVU5CSDhlaA==

Body

{"return_ids":["4035318504086604100"],"order_ids":["577686530908261117"],"buyer_user_ids":["7493996903972308733"],"return_types":["REFUND"],"return_status":["RETURN_OR_REFUND_REQUEST_PENDING"],"seller_proposed_return_type":["PARTIAL_REFUND"],"create_time_ge":1690340825,"arbitration_status":["IN_PROGRESS"],"update_time_ge":1690340825,"update_time_lt":1690340825,"locale":"en-US","create_time_lt":1690340825}

• REFUND: Seller will issue a refund without return. The buyer is not required to send the item(s) back to the seller.
• RETURN_AND_REFUND: Buyer is required to send the item(s) back to the seller. The seller will need to review the condition of the returned item(s) before a refund can be issued to the buyer.
• REPLACEMENT: The buyer requires the seller to replace the item(s).
• EXCHANGE: The buyer requires the seller to exchange the item(s). | ^^return_status |string |RETURN_OR_REFUND_REQUEST_PENDING |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 platform.
• 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 package.
• RETURN_OR_REFUND_REQUEST_SUCCESS: The return/refund request was approved. 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.
• EXCHANGE_REQUEST_PENDING: Buyer has initiated an exchange request. The request is pending review by seller.
• EXCHANGE_REQUEST_REFUND_SUCCESS: Buyer's exchange request was resolved by refund due to insufficient inventory.
• EXCHANGE_REQUEST_CANCEL: Buyer canceled the exchange request.
• EXCHANGE_REQUEST_COMPLETE: Seller has approved the buyer's exchange request, platform will generate a new order for seller to fulfill. | ^^arbitration_status |string |IN_PROGRESS |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 | ^^role |string |BUYER |Return initiation role. Available values:
• BUYER
• SELLER
• OPERATOR : TikTok Shop platform operator.
• SYSTEM: TikTok Shop system. Please see "API overview" to learn more about roles. | ^^return_reason |string |ecom_order_to_ship_canceled_reason_created_by_mistakes |Reason for return. | ^^return_reason_text |string |Order created by mistake |Reason for return, in localized text. You can change language using the locale request parameter. | ^^shipment_type |string |PLATFORM |The shipment method the buyer selected to send the item(s) back to seller Available values:
• PLATFORM: Buyer will use TikTok Shop's shipping service to send the items back to seller. Use the handover_method field to see which handover method the buyer is using, drop_off or pickup.
• BUYER_ARRANGE: Buyer will arrange shipment to send the item(s) back to seller. | ^^handover_method |string |DROP_OFF |The handover method buyer chooses to use when returning item(s) to seller using platform's shipping service.
• DROP_OFF: buyer will drop off the item(s) at courier
• PICKUP: buyer is scheduling a pick up service offered by the courier. | ^^return_tracking_number |string |213456789098765433456 |The tracking number of parcels when buyer returns the item(s). | ^^return_provider_name |string |J&T Express |The provider name of parcel when buyer returns the item(s). | ^^return_provider_id |string |TH27014E9R5Q4G |The provider ID of parcel when buyer returns the items. | ^^pre_return_id |string |4035310341095393452 |The previous return ID the current return order is edited from. | ^^next_return_id |string |4035310341095393463 |The next return ID the current return order is edited to. | ^^can_buyer_keep_item |bool |true |Whether buyer can keep the item(s) in a return or replacement process. | ^^update_time |int |1690453136 |Return update time. Unix timestamp. | ^^seller_next_action_response |[]object | |Seller's next action and deadline. | ^^^action |string |SELLER_RESPOND_REFUND |Seller's next action. Available values:
• SELLER_RESPOND_REFUND
• SELLER_RESPOND_RETURN
• SELLER_RESPOND_RECEIVE_PACKAGE
• SELLER_RESPOND_REPLACEMENT | ^^^deadline |int |1690554680 |Indicates the deadline for when seller must perform the next action. | ^^create_time |int |1690451136 |Return create time. Unix timestamp. | ^^return_line_items |[]object | |Return order lines items. | ^^^return_line_item_id |string |4035227657962164811 |Return order line ID. | ^^^order_line_item_id |string |576473917261451851 |Order line ID. | ^^^sku_id |string |2729382476852921560 |SKU ID. | ^^^sku_name |string |1#, Standard |SKU name. | ^^^product_name |string |(SP) [PROMO BUNDLING] NICE Tissue Facial 180s x 5 pcs |Product name. | ^^^seller_sku |string |PUTIH 1 TALI |SKU name defined by seller. | ^^^product_image |object | |Product image information. | ^^^^url |string |https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447 |Product image URL. | ^^^^width |int |200 |Product image width. Units: pixels (px). | ^^^^height |int |200 |Product image height. Units: pixels (px). | ^^^refund_amount |object | |Refund amount details. | ^^^^currency |string |USD |Payment currency. | ^^^^refund_total |string |1.23 |Total refund amount to buyer. | ^^^^refund_subtotal |string |1 |Subtotal refund amount to buyer. | ^^^^refund_shipping_fee |string |0.2 |Shipping fee refund amount to buyer. | ^^^^refund_tax |string |0.03 |Tax refund amount to buyer. | ^^^^retail_delivery_fee |string |0.1 |Retail delivery fee takes effect once platform GMV exceeds 500,000 USD, according to US Colorado states' compliance rules. | ^^^^buyer_service_fee |string |0.1 |Buyer service fee. | ^^^return_sub_line_items |[]object | |Return sub order lines items. Sub items represent skus that belong to a "virtual bundle" that has been defined by a seller. The sub_items will include all relevant information about each item that is a part of the virtual bundle. | ^^^^return_sub_line_item_id |string |4035227657962164812 |Return sub order line ID. | ^^^^return_line_item_id |string |4035227657962164811 |Return order line ID. | ^^^^sub_order_line_item_id |string |576473917261451852 |Sub order line ID. | ^^^^order_line_item_id |string |576473917261451851 |Order line ID. | ^^^^sku_id |string |2729382476852921560 |SKU ID. | ^^^^sku_name |string |1#, Standard |SKU name. | ^^^^product_image |object | |Product image information. | ^^^^^url |string |https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447 |Product image URL. | ^^^^^width |int |200 |Product image width. Units: pixels (px). | ^^^^^height |int |200 |Product image height. Units: pixels (px). | ^^^^product_name |string |(SP) [PROMO BUNDLING] NICE Tissue Facial 180s x 5 pcs |Product name. | ^^^^seller_sku |string |PUTIH 1 TALI |SKU name defined by seller. | ^^^^refund_amount |object | |Refund amount details. | ^^^^^currency |string |USD |Payment currency. | ^^^^^refund_total |string |1.23 |Total refund amount to buyer. | ^^^^^refund_subtotal |string |1 |Subtotal refund amount to buyer. | ^^^^^refund_shipping_fee |string |0.2 |Shipping fee refund amount to buyer. | ^^^^^refund_tax |string |0.03 |Tax refund amount to buyer. | ^^^^^retail_delivery_fee |string |0.1 |Retail delivery fee takes effect once platform GMV exceeds 500,000 USD, according to US Colorado states' compliance rules. | ^^^^^buyer_service_fee |string |0.1 |Buyer service fee. | ^^discount_amount |[]object | |Discount refund details. | ^^^currency |string |USD |The discount currency. | ^^^product_seller_discount |string |0.1 |The refund amount of product seller discount. | ^^^shipping_fee_platform_discount |string |0.1 |The refund amount of shipping fee platform discount. | ^^^shipping_fee_seller_discount |string |0.1 |The refund amount of shipping fee seller discount. | ^^^product_platform_discount |string |0.1 |The refund amount of platform discount. | ^^shipping_fee_amount |[]object | |The return shipping fee details. | ^^^currency |string |USD |Return shipping fee currency. | ^^^seller_paid_return_shipping_fee |string |0.1 |The amount of return shipping fee seller paid. | ^^^platform_paid_return_shipping_fee |string |0.1 |The amount of return shipping fee platform paid. | ^^^buyer_paid_return_shipping_fee |string |0.1 |The amount of return shipping fee buyer paid. | ^^refund_amount |object | |Total refund amount to buyer. | ^^^currency |string |USD |Refund currency. | ^^^refund_total |string |1.23 |Total refund amount. | ^^^refund_subtotal |string |1 |Subtotal refund amount. This is the total price of all items returned. | ^^^refund_shipping_fee |string |0.2 |Shipping fee refund. | ^^^refund_tax |string |0.03 |Tax fee refund. | ^^^retail_delivery_fee |string |0.1 |Retail delivery fee takes effect once platform GMV exceeds 500,000 USD, according to US Colorado states' compliance rules. | ^^^buyer_service_fee |string |0.1 |Buyer service fee. | ^^return_shipping_document_type |string |SHIPPING_LABEL |The type of return shipping document selected by the buyer. Available values:
• SHIPPING_LABEL
• QR_CODE - QR Code with Box
• QR_CODE_NBNL - QR Code with No Box No Label | ^^return_method |string |SELLER_ARRANGE |Return method:
• SELLER_SHIPPED: Seller offers the return shipping service.
• BUYER_SHIPPED: Buyer offers the return shipping service.
• PLATFORM_SHIPPED: TikTok Shop offers the return shipping service. | ^^is_combined_return |bool |true |This field will return true if the buyer is asking to combine multiple returns into one return package. | ^^combined_return_id |string |4035309948547073951 |If is_combined_return is true, this field will return the combined_return_id associated with the combined return. | ^^seller_proposed_return_type |string |PARTIAL_REFUND |Seller proposed return type:
• PARTIAL_REFUND | ^^partial_refund |object | |Partial refund details. | ^^^currency |string |IDR |Partial refund currency | ^^^amount |string |10 |The partial refund amount offered by seller. Note: only seller proposed partial refund will return this field. | ^^buyer_rejected_partial_refund |bool |true |Only return this field when seller initiated the partial refund. Available values:
• TRUE: Buyer reject the seller partial refund offer.
• FALSE: Buyer accept the seller partial refund offer or awaiting buyer response. | ^^return_warehouse_address |object | |The return warehouse address details provided by the seller. | ^^^full_address |string |1199 Coleman Ave San Jose, CA 95110 |The full return warehouse address. | ^^is_quick_refund |bool |false |If the return hit the quick refund strategy, the seller cannot reject the received package | ^total_count |int |100 |The number of returns that meet the query conditions. | ^next_page_token |string |aDU2dHIzMlFhME5CUzJKUDhDdVJhTDM1WmJkeFVTVW9LTkRaSnNaZCtuWjJXVU5CSDhlaA== |An opaque token used to retrieve the next page of a paginated result set. Provide this value in the page_token parameter of your request if the current response does not return all the results. |

{"code":0,"data":{"return_orders":[{"order_id":"577686530908261117","return_id":"4035318504086604100","return_type":"REFUND","return_status":"RETURN_OR_REFUND_REQUEST_PENDING","arbitration_status":"IN_PROGRESS","role":"BUYER","return_reason":"ecom_order_to_ship_canceled_reason_created_by_mistakes","return_reason_text":"Order created by mistake","shipment_type":"PLATFORM","handover_method":"DROP_OFF","return_tracking_number":"213456789098765433456","return_provider_name":"J\u0026T Express","return_provider_id":"TH27014E9R5Q4G","pre_return_id":"4035310341095393452","next_return_id":"4035310341095393463","can_buyer_keep_item":true,"update_time":1690453136,"seller_next_action_response":[{"action":"SELLER_RESPOND_REFUND","deadline":1690554680}],"create_time":1690451136,"return_line_items":[{"return_line_item_id":"4035227657962164811","order_line_item_id":"576473917261451851","sku_id":"2729382476852921560","sku_name":"1#, Standard","product_name":"(SP) [PROMO BUNDLING] NICE Tissue Facial 180s x 5 pcs","seller_sku":"PUTIH 1 TALI","product_image":{"url":"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447","width":200,"height":200},"refund_amount":{"currency":"USD","refund_total":"1.23","refund_subtotal":"1","refund_shipping_fee":"0.2","refund_tax":"0.03","retail_delivery_fee":"0.1","buyer_service_fee":"0.1"},"return_sub_line_items":[{"return_sub_line_item_id":"4035227657962164812","return_line_item_id":"4035227657962164811","sub_order_line_item_id":"576473917261451852","order_line_item_id":"576473917261451851","sku_id":"2729382476852921560","sku_name":"1#, Standard","product_image":{"url":"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447","width":200,"height":200},"product_name":"(SP) [PROMO BUNDLING] NICE Tissue Facial 180s x 5 pcs","seller_sku":"PUTIH 1 TALI","refund_amount":{"currency":"USD","refund_total":"1.23","refund_subtotal":"1","refund_shipping_fee":"0.2","refund_tax":"0.03","retail_delivery_fee":"0.1","buyer_service_fee":"0.1"}}]}],"discount_amount":[{"currency":"USD","product_seller_discount":"0.1","shipping_fee_platform_discount":"0.1","shipping_fee_seller_discount":"0.1","product_platform_discount":"0.1"}],"shipping_fee_amount":[{"currency":"USD","seller_paid_return_shipping_fee":"0.1","platform_paid_return_shipping_fee":"0.1","buyer_paid_return_shipping_fee":"0.1"}],"refund_amount":{"currency":"USD","refund_total":"1.23","refund_subtotal":"1","refund_shipping_fee":"0.2","refund_tax":"0.03","retail_delivery_fee":"0.1","buyer_service_fee":"0.1"},"return_shipping_document_type":"SHIPPING_LABEL","return_method":"SELLER_ARRANGE","is_combined_return":true,"combined_return_id":"4035309948547073951","seller_proposed_return_type":"PARTIAL_REFUND","partial_refund":{"currency":"IDR","amount":"10"},"buyer_rejected_partial_refund":true,"return_warehouse_address":{"full_address":"1199 Coleman Ave San Jose, CA 95110"},"is_quick_refund":false}],"total_count":100,"next_page_token":"aDU2dHIzMlFhME5CUzJKUDhDdVJhTDM1WmJkeFVTVW9LTkRaSnNaZCtuWjJXVU5CSDhlaA=="},"message":"Success","request_id":"202203070749000101890810281E8C70B7"}

For common error codes, refer to How to call TikTok Shop APIs - Common Error Code