Search Cancellations

Use this API to search and retrieve one or more order cancellations.

---

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: [1-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. |

• CANCEL: Cancel by seller or system.
• BUYER_CANCEL: Cancel by buyer. Need to be approved by seller or system. | cancel_status |[]string |N |["CANCELLATION_REQUEST_PENDING"] |List of order cancellation statuses. Possible values:
• CANCELLATION_REQUEST_PENDING
• CANCELLATION_REQUEST_SUCCESS
• CANCELLATION_REQUEST_CANCEL
• CANCELLATION_REQUEST_COMPLETE

Please see "API Overview" for more information about these statuses. | create_time_ge |int |N |1690340825 |Filter cancellations to show only orders that have been created after a specified date and time. Unix timestamp. | create_time_lt |int |N |1690340825 |Filter cancellations to show only orders that have been created before a specified date and time. Unix timestamp. | update_time_ge |int |N |1690340825 |Filter cancellations to show only orders that have been updated after a specified date and time. Unix timestamp. | update_time_lt |int |N |1690340825 |Filter cancellations to show only orders that have been updated before a specified date and time. Unix timestamp. | locale |string |N |en-US |The BCP-47 locale codes for displaying the order, delimited by commas. Default: en-US Refer to Locale codes for the list of supported locale codes. |

Query

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

Body

{"cancel_ids":["577087614418520388"],"order_ids":["577087614418520388"],"buyer_user_ids":["7494845267308415300"],"cancel_types":["CANCEL"],"cancel_status":["CANCELLATION_REQUEST_PENDING"],"create_time_ge":1690340825,"create_time_lt":1690340825,"update_time_ge":1690340825,"update_time_lt":1690340825,"locale":"en-US"}

• CANCEL: Cancel by seller or system.
• BUYER_CANCEL: Cancel by buyer. Need to be approved by seller or system. | ^^cancel_status |string |CANCELLATION_REQUEST_PENDING |Order cancellation status. Possible values:
• CANCELLATION_REQUEST_PENDING
• CANCELLATION_REQUEST_SUCCESS
• CANCELLATION_REQUEST_CANCELLED
• CANCELLATION_REQUEST_COMPLETE | ^^role |string |BUYER |Order cancellation initiator. Possible values:
• BUYER
• SELLER
• SYSTEM | ^^cancel_reason |string |ecom_order_to_ship_canceled_reason_created_by_mistakes |Order cancellation reason. | ^^cancel_reason_text |string |Order created by mistake |Order cancellation reason, localized to another language. You can change language using the locale field in the request parameter. | ^^create_time |int |1690451136 |Order cancellation create time. Unix timestamp. | ^^update_time |int |1690451136 |Order cancellation update time. Unix timestamp. | ^^seller_next_action_response |[]object | |Seller's next action and deadline. | ^^^action |string |SELLER_RESPOND_CANCEL |Optional. For buyer-initiated cancellation requests that still require seller handling, the action value is SELLER_RESPOND_CANCEL | ^^^deadline |int |1690554680 |Unix timestamp indicating the deadline for when the seller must perform the next action. | ^^refund_amount |object | |Refund amount information. | ^^^currency |string |USD |Refund currency. | ^^^refund_total |string |1.23 |Total refund amount to the buyer. | ^^^refund_subtotal |string |1 |Subtotal refund amount to the buyer. | ^^^refund_shipping_fee |string |0.2 |Shipping fee refund amount to the buyer. | ^^^refund_tax |string |0.03 |Tax refund amount to the buyer. | ^^^retail_delivery_fee |string |0.1 |Retail delivery fee takes effect once platform GMV exceeds $500,000 USD, according to Colorado (US) compliance rules. | ^^^buyer_service_fee |string |1000 |Only for the ID market. Platform will charge the buyer a service fee depending on the scenario. | ^^cancel_line_items |[]object | |Cancellation line items. | ^^^cancel_line_item_id |string |4035227913481196964 |Cancellation line item ID. | ^^^order_line_item_id |string |576468844534141348 |Order line item ID. | ^^^sku_id |string |2729382476852921560 |SKU ID. | ^^^sku_name |string |1#, Standard |SKU name. | ^^^product_image |object | |Product image object. Contains 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. Unit: px | ^^^^height |int |200 |Product image height. Unit: px | ^^^product_name |string |bundle No Heel Flat Heel Summer Winter Round Toe |Product name. | ^^^seller_sku |string |YYAPC23078TRT30 |SKU name defined by the seller. | ^^^refund_amount |object | |Refund amount information. | ^^^^currency |string |USD |Refund currency. | ^^^^refund_total |string |1.23 |Total refund amount to the buyer. | ^^^^refund_subtotal |string |1 |Subtotal refund amount to the buyer. | ^^^^refund_shipping_fee |string |0.2 |Shipping fee refund amount to the buyer. | ^^^^refund_tax |string |0.03 |Tax refund amount to the buyer. | ^^^^retail_delivery_fee |string |0.1 |Retail delivery fee takes effect once platform GMV exceeds 500,000 USD, according to Colorado (US) compliance rules. | ^^^^buyer_service_fee |string |1000 |Only for the ID market. Platform will charge the buyer service fee depending on the scenario. | ^^^cancel_sub_line_items |[]object | |Cancellation sub line 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. | ^^^^cancel_sub_line_item_id |string |4035227657962164812 |Cancellation sub line item ID. | ^^^^cancel_line_item_id |string |4035227657962164811 |Cancellation line item ID. | ^^^^sub_order_line_item_id |string |576473917261451852 |Sub Order line item ID. | ^^^^order_line_item_id |string |576473917261451851 |Order line item ID. | ^^^^sku_id |string |2729382476852921560 |SKU ID. | ^^^^sku_name |string |1#, Standard |SKU name. | ^^^^product_image |object | |Product image object. Contains 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. Unit: px | ^^^^^height |int |200 |Product image height. Unit: px | ^^^^product_name |string |bundle No Heel Flat Heel Summer Winter Round Toe |Product name. | ^^^^seller_sku |string |YYAPC23078TRT30 |SKU name defined by the seller. | ^^^^refund_amount |object | |Refund amount information. | ^^^^^currency |string |USD |Refund currency. | ^^^^^refund_total |string |1.23 |Total refund amount to the buyer. | ^^^^^refund_subtotal |string |1 |Subtotal refund amount to the buyer. | ^^^^^refund_shipping_fee |string |0.2 |Shipping fee refund amount to the buyer. | ^^^^^refund_tax |string |0.03 |Tax refund amount to the buyer. | ^^^^^retail_delivery_fee |string |0.1 |Retail delivery fee takes effect once platform GMV exceeds $500,000 USD, according to Colorado (US) compliance rules. | ^^^^^buyer_service_fee |string |1000 |Only for the ID market. Platform will charge the buyer a service fee depending on the scenario. | ^^cancel_id |string |4035318504086604100 |The identifier of a specific order cancellation. | ^^should_replenish_stock |bool |false |Should seller replenish the stock when order cancelled successfully. | ^total_count |int |100 |The number of cancellations 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":{"cancellations":[{"order_id":"577087614418520388","cancel_type":"REQUEST_CANCEL_REFUND","cancel_status":"CANCELLATION_REQUEST_PENDING","role":"BUYER","cancel_reason":"ecom_order_to_ship_canceled_reason_created_by_mistakes","cancel_reason_text":"Order created by mistake","create_time":1690451136,"update_time":1690451136,"seller_next_action_response":[{"action":"SELLER_RESPOND_CANCEL","deadline":1690554680}],"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":"1000"},"cancel_line_items":[{"cancel_line_item_id":"4035227913481196964","order_line_item_id":"576468844534141348","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":"bundle No Heel Flat Heel Summer Winter Round Toe","seller_sku":"YYAPC23078TRT30","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":"1000"},"cancel_sub_line_items":[{"cancel_sub_line_item_id":"4035227657962164812","cancel_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":"bundle No Heel Flat Heel Summer Winter Round Toe","seller_sku":"YYAPC23078TRT30","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":"1000"}}]}],"cancel_id":"4035318504086604100","should_replenish_stock":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