Get Return Records

GET

/return_refund/202309/returns/{return_id}/records

Use this API to retrieve the record entries for a specific return request. Each item in data.records represents an action or lifecycle event for the specified return_id.

Authorizations

• accessToken

Parameters

Path Parameters

return_id

required

string

A unique identifier for a TikTok Shop return request.

Query Parameters

shop_cipher

required

string

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

locale

string

The BCP-47 locale codes for displaying the return reason, delimited by commas. Default: en-US Refer to Locale codes for the list of supported locale codes.

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

records

A list of return records.

Array<object>

object

event

The event type that represents which lifecycle event this record describes. It can vary depending on the current status and the return flow of the request, including the initial request, seller actions, shipment events, and timeout or system events.

string

role

The actor that initiated this lifecycle event. Possible values:

• BUYER
• SELLER
• OPERATOR: The action was triggered manually by a customer service agent.
• SYSTEM: The action was triggered automatically due to a policy reason.

string

Allowed values: BUYER SELLER OPERATOR SYSTEM

description

A human-readable description of this lifecycle event.

string

reason_text

The corresponding text for a return reason, localized based on the locale input parameter.

string

note

A note associated with the return record. Use role to identify the actor for the event.

string

images

Images provided by the seller or buyer. You can use the role field to differentiate whether the images are from the seller or buyer.

Array<object>

object

url

URL of the image.

string

width

The width of image. Unit: px

integer format: int64

height

The height of image. Unit: px

integer format: int64

videos

Videos uploaded by the buyer. Only buyers are allowed to upload videos.

Array<object>

object

url

Video URL.

string

cover

Video thumbnail image.

string

width

Video image width. Unit: px

integer format: int64

height

Video image height. Unit: px

integer format: int64

duration_millis

Video duration. Unit: milliseconds

integer format: int64

create_time

The Unix timestamp, in seconds, when this record entry was created.

integer format: int64

Example

{
  "code": 0,
  "data": {
    "records": [
      {
        "event": "ORDER_RETURN",
        "role": "BUYER",
        "description": "Customer submitted a return request",
        "reason_text": "Wrong product was sent",
        "note": "Reach an agreement with the buyer",
        "images": [
          {
            "url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447",
            "width": 200,
            "height": 200
          }
        ],
        "videos": [
          {
            "url": "https://v16m-default.akamaized.net/1e26046c3df91cd008d2ababba9445e2/65005d33/video/tos/maliva/tos-maliva-v-d8ca36-us/oQVCbIQemDpQxI9lHsg9IXQAb7mwgBabababab",
            "cover": "https://p16-oec-va.ibyteimg.com/musically-maliva-obj/998d0381960bda1ef272f4a7724cf5ed~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405489",
            "width": 200,
            "height": 200,
            "duration_millis": 3000
          }
        ],
        "create_time": 1690532213
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}