Create Return

POST

/return_refund/202602/returns

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.

Authorizations

• accessToken

Parameters

Query Parameters

shop_cipher

required

string

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

idempotency_key

string

Idempotency Key

Request Body^required

Media typeapplication/json

object

order_id

required

Tiktok Shop order id

string

skus

Skus

Array<object>

object

sku_id

required

TikTok Shop SKU ID to include in the refund calculation.

string

quantity

required

Quantity of this SKU to include in the refund calculation.

integer format: int64

order_line_item_ids

Specifies the order line IDs to include in the return request. Use this field to select order lines when an order is split into multiple packages. Do not provide non-empty values in both order_line_item_ids and order_line_list in the same request. If order_line_item_ids, order_line_list, and skus are all omitted, all order lines in the order are included. Note: This is a legacy field; new integrations should use order_line_list instead.

Array<string>

return_reason

required

Seller’s reason to create a return

string

return_type

required

Which type to create:

• REFUND
• RETURN_AND_REFUND

string

refund_total

Total refund amount to the buyer. The total refund amount can not exceed the refundable amount

string

currency

Currency of the refund amount. It should be the same as the currency of the TikTok Shop order. Required when refund_total is provided.

string

shipment_type

Specifies the return shipping method the buyer uses to send items back to the seller in a return request. Supported values:

• PLATFORM
• BUYER_ARRANGE

string

handover_method

Optional. Only applicable when shipment_type is PLATFORM. Specifies the handover method the buyer uses to return the item through platform-supported shipping. Supported values:

• DROP_OFF
• PICKUP

string

order_line_list

Specifies the line items to include in the return request and supports bundle order splitting. Every entry must include order_line_item_id. For a bundle sub-item, also include sub_order_line_item_id; omit sub_order_line_item_id for a normal order line. Do not mix normal order lines and bundle sub-items in the same request. Note: This field is completely backward compatible with the legacy order_line_item_ids field.

Array<object>

object

order_line_item_id

The corresponding order line ID

string

sub_order_line_item_id

The sub-order-line ID inside a bundle product

• Required for bundle products
• Not required for non-bundle products

string

Example

{
  "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"
    }
  ]
}

Responses

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_id

The identifier of a specific return request.

string

return_status

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.

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

Example

{
  "code": 0,
  "data": {
    "return_id": "4035319218955782461",
    "return_status": "RETURN_OR_REFUND_REQUEST_PENDING"
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}