(12) Return status change

POST

The return status change webhook is triggered when the return_status of an order changes:

• The BUYER initiates a return or refund request and is pending SELLER review: RETURN_OR_REFUND_REQUEST_PENDING
• The SELLER declines the BUYER’s return or refund request: REFUND_OR_RETURN_REQUEST_REJECT
• The return request is approved and the SELLER is waiting for the BUYER to return the approved items: AWAITING_BUYER_SHIP. If the BUYER doesn’t ship the items to the SELLER before the deadline, the request will be closed automatically.
• To return the items to the SELLER, the BUYER drops off the package successfully or the BUYER ships the package and uploads the tracking number: BUYER_SHIPPED_ITEM
• The SELLER declines the refund request for the return: REJECT_RECEIVE_PACKAGE
• The SELLER accepts the refund request or issues a refund for the return: RETURN_OR_REFUND_REQUEST_SUCCESS
• The BUYER or SYSTEM closes the return or refund request: RETURN_OR_REFUND__REQUEST_CANCELLED
• The return or refund is successful: RETURN_OR_REFUND_REQUEST_COMPLETE

Additionally, a BUYER may request an identical replacement item instead of a refund:

• The BUYER initiates a replacement request and is pending SELLER review: REPLACEMENT_REQUEST_PENDING
• The SELLER declines the BUYER’s replacement request: REPLACEMENT_REQUEST_REJECT
• The SELLER decides to issue a refund to the BUYER without replacement: REPLACEMENT_REQUEST_REFUND_SUCCESS
• The BUYER cancels the replacement request: REPLACEMENT_REQUEST_CANCEL
• The SELLER approves the replacement request: REPLACEMENT_REQUEST_COMPLETE

Authorizations

• webhookSignature

Request Body^required

Media typeapplication/json

object

type

required

The ID of the webhook type.

integer

Allowed value: 12

tts_notification_id

The ID of the notification.

string

shop_id

The shop ID.

string

timestamp

The Unix timestamp when the webhook was triggered.

integer format: int64

data

object

order_id

The identification of a TikTok Shop order

string

return_role

Return or refund request user, with possible values:

• BUYER
• SELLER
• SYSTEM

string

Allowed values: BUYER SELLER SYSTEM

return_type

The return or refund request type, with possible values:

• REFUND
• REPLACEMENT
• RETURN_AND_REFUND

string

Allowed values: REFUND REPLACEMENT RETURN_AND_REFUND

return_status

The return status for a request, with possible values:

• AWAITING_BUYER_SHIP
• BUYER_SHIPPED_ITEM
• REFUND_OR_RETURN_REQUEST_REJECT
• REJECT_RECEIVE_PACKAGE
• REPLACEMENT_REQUEST_CANCEL
• REPLACEMENT_REQUEST_COMPLETE
• REPLACEMENT_REQUEST_PENDING
• REPLACEMENT_REQUEST_REFUND_SUCCESS
• REPLACEMENT_REQUEST_REJECT
• RETURN_OR_REFUND_REQUEST_CANCEL
• RETURN_OR_REFUND_REQUEST_COMPLETE
• RETURN_OR_REFUND_REQUEST_PENDING
• RETURN_OR_REFUND_REQUEST_SUCCESS

string

Allowed values: AWAITING_BUYER_SHIP BUYER_SHIPPED_ITEM REFUND_OR_RETURN_REQUEST_REJECT REJECT_RECEIVE_PACKAGE REPLACEMENT_REQUEST_CANCEL REPLACEMENT_REQUEST_COMPLETE REPLACEMENT_REQUEST_PENDING REPLACEMENT_REQUEST_REFUND_SUCCESS REPLACEMENT_REQUEST_REJECT RETURN_OR_REFUND_REQUEST_CANCEL RETURN_OR_REFUND_REQUEST_COMPLETE RETURN_OR_REFUND_REQUEST_PENDING RETURN_OR_REFUND_REQUEST_SUCCESS

return_id

The identifier of a specific return

string

create_time

The time when the request was created.

integer format: int64

update_time

The time when return order status update, represented as a Unix timestamp (seconds).

integer format: int64

Example

{
  "type": 12,
  "tts_notification_id": "7327112393057371910",
  "shop_id": "7494049642642441621",
  "timestamp": 1644412885,
  "data": {
    "order_id": "576486316948490001",
    "return_role": "BUYER",
    "return_type": "REFUND",
    "return_status": "RETURN_OR_REFUND_REQUEST_PENDING",
    "return_id": "576486316948490001",
    "create_time": 1627587600,
    "update_time": 1644412885
  }
}

Responses

200

Return HTTP 200 to acknowledge receipt.