Skip to content
TikTok Shop Partner API

Search Returns

POST
/return_refund/202602/returns/search

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.

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

Request Body

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

List of return IDs. Each ID must be a base-10 integer string that fits in a signed 64-bit integer.

Array<string>
order_ids

List of TikTok Shop order IDs. Each ID must be a base-10 integer string that fits in a signed 64-bit integer.

Array<string>
buyer_user_ids

List of TikTok Shop buyer user IDs. Each ID must be a base-10 integer string that fits in a signed 64-bit integer.

Array<string>
return_types

List of return types. Available values:

  • REFUND
  • RETURN_AND_REFUND
  • REPLACEMENT
  • EXCHANGE
Array<string>
Allowed values: REFUND RETURN_AND_REFUND REPLACEMENT EXCHANGE
return_status

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.
Array<string>
Allowed values: RETURN_OR_REFUND_REQUEST_PENDING REFUND_OR_RETURN_REQUEST_REJECT AWAITING_BUYER_SHIP BUYER_SHIPPED_ITEM REJECT_RECEIVE_PACKAGE RETURN_OR_REFUND_REQUEST_SUCCESS RETURN_OR_REFUND_REQUEST_CANCEL RETURN_OR_REFUND_REQUEST_COMPLETE REPLACEMENT_REQUEST_PENDING REPLACEMENT_REQUEST_REJECT REPLACEMENT_REQUEST_REFUND_SUCCESS REPLACEMENT_REQUEST_CANCEL REPLACEMENT_REQUEST_COMPLETE AWAITING_BUYER_RESPONSE EXCHANGE_REQUEST_PENDING EXCHANGE_REQUEST_REFUND_SUCCESS EXCHANGE_REQUEST_CANCEL EXCHANGE_REQUEST_COMPLETE
seller_proposed_return_type

List of seller proposed return types. Available values:

  • PARTIAL_REFUND
Array<string>
Allowed values: PARTIAL_REFUND
create_time_ge

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.
integer format: int64
arbitration_status

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.
Array<string>
Allowed values: IN_PROGRESS SUPPORT_BUYER SUPPORT_SELLER CLOSED
update_time_ge

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.
integer format: int64
update_time_lt

Filter returns to those updated before the specified time. Provide a Unix timestamp in seconds.

integer format: int64
locale

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.

string
create_time_lt

Filter returns to those created before the specified time. Provide a Unix timestamp in seconds.

integer format: int64
Example
{
  "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
}

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
return_orders

List of returns in the current page. This field is omitted when the current page contains no return records.

Array<object>
object
order_id

TikTok Shop order ID.

string
return_id

The identifier of a specific return.

string
return_type

Return type. Available values:

  • 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).
string
Allowed values: REFUND RETURN_AND_REFUND REPLACEMENT EXCHANGE
return_status

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.
string
Allowed values: RETURN_OR_REFUND_REQUEST_PENDING REFUND_OR_RETURN_REQUEST_REJECT AWAITING_BUYER_SHIP BUYER_SHIPPED_ITEM REJECT_RECEIVE_PACKAGE RETURN_OR_REFUND_REQUEST_SUCCESS RETURN_OR_REFUND_REQUEST_CANCEL RETURN_OR_REFUND_REQUEST_COMPLETE REPLACEMENT_REQUEST_PENDING REPLACEMENT_REQUEST_REJECT REPLACEMENT_REQUEST_REFUND_SUCCESS REPLACEMENT_REQUEST_CANCEL REPLACEMENT_REQUEST_COMPLETE AWAITING_BUYER_RESPONSE EXCHANGE_REQUEST_PENDING EXCHANGE_REQUEST_REFUND_SUCCESS EXCHANGE_REQUEST_CANCEL EXCHANGE_REQUEST_COMPLETE
arbitration_status

Arbitration status. Available values:

  • IN_PROGRESS: The TikTok Shop platform operator is processing arbitration and may request additional information from the seller.
  • SUPPORT_BUYER: The platform operator supports the buyer.
  • SUPPORT_SELLER: The platform operator supports the seller.
  • CLOSED: Arbitration is closed.
string
Allowed values: IN_PROGRESS SUPPORT_BUYER SUPPORT_SELLER CLOSED
role

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.
string
Allowed values: BUYER SELLER OPERATOR SYSTEM
return_reason

Machine-readable reason code for the return. Use return_reason_text for localized display text.

string
return_reason_text

Reason for return, in localized text. You can change language using the locale request parameter.

string
shipment_type

The shipment method selected by the buyer for sending the item(s) back to the seller. Available values:

  • PLATFORM: The buyer uses TikTok Shop’s shipping service. See handover_method for whether the buyer uses DROP_OFF or PICKUP.
  • BUYER_ARRANGE: The buyer arranges the return shipment.
string
Allowed values: PLATFORM BUYER_ARRANGE
handover_method

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.
string
return_tracking_number

The tracking number of parcels when buyer returns the item(s).

string
return_provider_name

The provider name of parcel when buyer returns the item(s).

string
return_provider_id

The provider ID of parcel when buyer returns the items.

string
pre_return_id

The previous return ID the current return order is edited from.

string
next_return_id

The next return ID the current return order is edited to.

string
can_buyer_keep_item

Indicates whether the buyer may keep the item(s). This field is returned as true for replacement requests and is omitted for other return types.

boolean
update_time

The time when the return was last updated, as a Unix timestamp in seconds.

integer format: int64
seller_next_action_response

Seller’s next action and deadline.

Array<object>
object
action

Seller’s next action. Available values:

  • SELLER_RESPOND_REFUND
  • SELLER_RESPOND_RETURN
  • SELLER_RESPOND_RECEIVE_PACKAGE
  • SELLER_RESPOND_REPLACEMENT
string
Allowed values: SELLER_RESPOND_REFUND SELLER_RESPOND_RETURN SELLER_RESPOND_RECEIVE_PACKAGE SELLER_RESPOND_REPLACEMENT
deadline

The deadline for the seller to perform the specified action, as a Unix timestamp in seconds.

integer format: int64
create_time

The time when the return was created, as a Unix timestamp in seconds.

integer format: int64
return_line_items

Return order lines items.

Array<object>
object
return_line_item_id

Return order line ID.

string
order_line_item_id

Order line ID.

string
sku_id

SKU ID.

string
sku_name

SKU name.

string
product_name

Product name.

string
seller_sku

SKU name defined by seller.

string
product_image

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
refund_amount

Refund amount details.

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
return_sub_line_items

Return sub-order line items. These items represent SKUs that belong to a “virtual bundle” defined by a seller. This field includes all relevant information about each item in the virtual bundle.

Array<object>
object
return_sub_line_item_id

Return sub order line ID.

string
return_line_item_id

Return order line ID.

string
sub_order_line_item_id

Sub order line ID.

string
order_line_item_id

Order line ID.

string
sku_id

SKU ID.

string
sku_name

SKU name.

string
product_image

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 seller.

string
refund_amount

Refund amount details.

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
discount_amount

Discount refund details.

Array<object>
object
currency

The discount currency.

string
product_seller_discount

The refund amount of product seller discount.

string
shipping_fee_platform_discount

The refund amount of shipping fee platform discount.

string
shipping_fee_seller_discount

The refund amount of shipping fee seller discount.

string
product_platform_discount

The refund amount of platform discount.

string
shipping_fee_amount

The return shipping fee details.

Array<object>
object
currency

Return shipping fee currency.

string
seller_paid_return_shipping_fee

The amount of return shipping fee seller paid.

string
platform_paid_return_shipping_fee

The amount of return shipping fee platform paid.

string
buyer_paid_return_shipping_fee

The amount of return shipping fee buyer paid.

string
refund_amount

Total refund amount to buyer.

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
return_shipping_document_type

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
string
Allowed values: SHIPPING_LABEL QR_CODE QR_CODE_NBNL
return_method

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.
string
is_combined_return

This field will return true if the buyer is asking to combine multiple returns into one return package.

boolean
combined_return_id

If is_combined_return is true, this field will return the combined_return_id associated with the combined return.

string
seller_proposed_return_type

Seller proposed return type:

  • PARTIAL_REFUND
string
partial_refund

Partial refund details.

object
currency

Refund currency must match the currency of the current return request.

string
amount

The partial refund amount seller would like to offer to the buyer

string
buyer_rejected_partial_refund

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.
boolean
return_warehouse_address

The return warehouse address details provided by the seller.

object
full_address

The full return warehouse address.

string
is_quick_refund

If the return hit the quick refund strategy, the seller cannot reject the received package

boolean
total_count

The number of returns that meet the query conditions.

integer format: int64
next_page_token

An opaque token used to retrieve the next page of a paginated result set. If next_page_token is non-empty, provide it in the page_token parameter of the next request. If next_page_token is empty, stop pagination.

string
Example
{
  "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&T 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": "PLATFORM_SHIPPED",
        "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"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec