Skip to main content

(12) Return status change

1. Trigger scenario

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

2. Data business parameters

ParameterDescriptionSample
order_idThe identification of a TikTok Shop order577087614418520388
return_roleReturn or refund request user, with possible values: * BUYER * SELLER * SYSTEMBUYER
return_typeThe return or refund request type, with possible values: * REFUND * REPLACEMENT * RETURN_AND_REFUNDREFUND
return_statusThe 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_SUCCESSRETURN_OR_REFUND_REQUEST_PENDING
return_idThe identifier of a specific return4035318504086604100
create_timeThe time when the request was created.1627587600
update_timeThe time when return order status update, represented as a Unix timestamp (seconds).1627587600

Event example​

JSONWord Wrap

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