Skip to content
TikTok Shop Partner API

Search Cancellations

POST
/return_refund/202602/cancellations/search

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
shop_cipher
required
string

Identifies the shop. Obtain it from the Get Authorized Shops API.

sort_field
string
Allowed values: create_time update_time

The returned results will be sorted by the specified field. Default: create_time Possible values:

  • create_time
  • update_time

Specify the order for sorting the returned results by using the sort_order parameter.

sort_order
string
Allowed values: ASC DESC

The sort order for the sort_field parameter. Default: ASC Possible values:

  • ASC: Ascending order
  • DESC: Descending order
page_size
string

The number of results to be returned per page. Default: 10. Valid range: [1-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.

Request Body

Section titled “Request Body”
Media typeapplication/json
object
cancel_ids

List of order cancellations IDs.

Array<string>
order_ids

List of TikTok Shop order IDs.

Array<string>
buyer_user_ids

List of TikTok Shop buyer user IDs.

Array<string>
cancel_types

List of order cancellation types. Possible values:

  • CANCEL: Cancel by seller or system.
  • BUYER_CANCEL: Cancel by buyer. Need to be approved by seller or system.
Array<string>
Allowed values: CANCEL BUYER_CANCEL
cancel_status

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.

Array<string>
Allowed values: CANCELLATION_REQUEST_PENDING CANCELLATION_REQUEST_SUCCESS CANCELLATION_REQUEST_CANCEL CANCELLATION_REQUEST_COMPLETE
create_time_ge

Filter cancellations to show only orders that have been created after a specified date and time. Unix timestamp.

integer format: int64
create_time_lt

Filter cancellations to show only orders that have been created before a specified date and time. Unix timestamp.

integer format: int64
update_time_ge

Filter cancellations to show only orders that have been updated after a specified date and time. Unix timestamp.

integer format: int64
update_time_lt

Filter cancellations to show only orders that have been updated before a specified date and time. Unix timestamp.

integer format: int64
locale

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.

string
Example
{
  "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"
}

Responses

Section titled “Responses”

200

Section titled “200”

Success

Media typeapplication/json
object
code

Status code; 0 means success.

integer format: int64
message

Success or failure message.

string
request_id

Request log ID.

string
data
object
cancellations

List of order cancellations.

Array<object>
object
order_id

TikTok Shop order ID.

string
cancel_type

Order cancellation type. Possible values:

  • CANCEL: Cancel by seller or system.
  • BUYER_CANCEL: Cancel by buyer. Need to be approved by seller or system.
string
Allowed values: CANCEL BUYER_CANCEL
cancel_status

Order cancellation status. Possible values:

  • CANCELLATION_REQUEST_PENDING
  • CANCELLATION_REQUEST_SUCCESS
  • CANCELLATION_REQUEST_CANCEL
  • CANCELLATION_REQUEST_COMPLETE
string
Allowed values: CANCELLATION_REQUEST_PENDING CANCELLATION_REQUEST_SUCCESS CANCELLATION_REQUEST_CANCEL CANCELLATION_REQUEST_COMPLETE
role

Order cancellation initiator. Possible values:

  • BUYER
  • SELLER
  • OPERATOR
  • SYSTEM
string
Allowed values: BUYER SELLER OPERATOR SYSTEM
cancel_reason

Order cancellation reason.

string
cancel_reason_text

Order cancellation reason, localized to another language. You can change language using the locale field in the request parameter.

string
create_time

The time when the order cancellation was created. Unix timestamp in seconds.

integer format: int64
update_time

The time when the order cancellation was last updated. Unix timestamp in seconds.

integer format: int64
seller_next_action_response

Seller’s next action and deadline.

Array<object>
object
action

Optional. For buyer-initiated cancellation requests that still require seller handling, the action value is SELLER_RESPOND_BUYER_CANCEL.

string
deadline

Unix timestamp in seconds indicating the deadline for the seller to perform the next action.

integer format: int64
refund_amount

Refund amount information.

object
currency

Payment currency.

string
refund_total

Total refund amount to buyer.

string
refund_subtotal

Subtotal refund amount to buyer.

string
refund_shipping_fee

Shipping fee refund amount to buyer.

string
refund_tax

Tax refund amount to buyer.

string
retail_delivery_fee

Retail delivery fee takes effect once platform GMV exceeds 500,000 USD, according to US Colorado states’ compliance rules.

string
buyer_service_fee

Buyer service fee.

string
cancel_line_items

Cancellation line items.

Array<object>
object
cancel_line_item_id

Cancellation line item ID.

string
order_line_item_id

Order line item ID.

string
sku_id

SKU ID.

string
sku_name

SKU name.

string
product_image

Product image object. Contains product image information.

object
url

Ignore this field. It is not yet supported.

string
width

Ignore this field. It is not yet supported.

integer format: int64
height

Ignore this field. It is not yet supported.

integer format: int64
product_name

Product name.

string
seller_sku

SKU name defined by the seller.

string
refund_amount

Refund amount information.

object
currency

Payment currency.

string
refund_total

Total refund amount to buyer.

string
refund_subtotal

Subtotal refund amount to buyer.

string
refund_shipping_fee

Shipping fee refund amount to buyer.

string
refund_tax

Tax refund amount to buyer.

string
retail_delivery_fee

Retail delivery fee takes effect once platform GMV exceeds 500,000 USD, according to US Colorado states’ compliance rules.

string
buyer_service_fee

Buyer service fee.

string
cancel_sub_line_items

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.

Array<object>
object
cancel_sub_line_item_id

Cancellation sub line item ID.

string
cancel_line_item_id

Cancellation line item ID.

string
sub_order_line_item_id

Sub Order line item ID.

string
order_line_item_id

Order line item ID.

string
sku_id

SKU ID.

string
sku_name

SKU name.

string
product_image

Product image object. Contains product image information.

object
url

Ignore this field. It is not yet supported.

string
width

Ignore this field. It is not yet supported.

integer format: int64
height

Ignore this field. It is not yet supported.

integer format: int64
product_name

Product name.

string
seller_sku

SKU name defined by the seller.

string
refund_amount

Refund amount information.

object
currency

Payment currency.

string
refund_total

Total refund amount to buyer.

string
refund_subtotal

Subtotal refund amount to buyer.

string
refund_shipping_fee

Shipping fee refund amount to buyer.

string
refund_tax

Tax refund amount to buyer.

string
retail_delivery_fee

Retail delivery fee takes effect once platform GMV exceeds 500,000 USD, according to US Colorado states’ compliance rules.

string
buyer_service_fee

Buyer service fee.

string
cancel_id

The identifier of a specific order cancellation.

string
should_replenish_stock

Should seller replenish the stock when order cancelled successfully.

boolean
total_count

The number of cancellations that meet the query conditions.

integer format: int64
next_page_token

An opaque token used to retrieve the next page of results. If this value is non-empty, provide it in the page_token parameter of the next request. An empty value indicates that there are no more results.

string
Example
{
  "code": 0,
  "data": {
    "cancellations": [
      {
        "order_id": "577087614418520388",
        "cancel_type": "CANCEL",
        "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_BUYER_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"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec