Tracking status update

POST

/fulfillment/202609/order/sof/track/update

This API is currently exclusive to the following markets: US, BR. This API is suitable for merchants to deliver and carry orders by themselves, without shipping orders through third-party service providers, that is, without shipping packages through 3PL, but orders sent by merchants. Merchants are allowed to use this API to return such orders and update the order track. The Action Code and Failed Reason in the input parameter are enumerated, as detailed in the document: https://partner.tiktokshop.com/docv2/page/1cjht3qx

Authorizations

• accessToken

Parameters

Query Parameters

shop_cipher

required

string

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

Request Body^required

Media typeapplication/json

object

country

required

Order Country.

string

order_id

required

TikTok Shop order ID.

string

external_tracking_url

Service provider’s track URL / official website link.

string

tracks

required

Trajectory node array; maximum number of entries per single request [50], processing results are returned one by one within the array. That is, in the interface, a maximum of 50 tracks can be postbacked per order at a time.

Array<object>

object

action_code

required

The standard trajectory node code must belong to the allowlist. See the below action code. The action code is limited, for the list of available enumerations, please refer to the documentation: https://partner.tiktokshop.com/docv2/page/1cjht3qx

integer format: int64

occur_time

required

Actual Trajectory Occurrence Time. Unix timestamp GMT (UTC+00:00). The unit is milliseconds.

integer format: int64

description

required

The original trajectory description of the caller.

string

failed_reason

Exception causes, details are listed below. See the below reason code. The reason code is limited, for the list of available enumerations, please refer to the documentation: https://partner.tiktokshop.com/docv2/page/1cjht3qx

string

proof_url

Third-party tracking proof links or credentials.

string

location

Location fields such as city, state, province, country, latitude and longitude;

object

country

Country.

string

state

State.

string

city

City.

string

zip_code

Zip code/post code.

string

tracking_no

required

The waybill number used when placing an order. If there is no tracking code, fill in the invoice id instead. And it may change in split shipment, it may change in different track in this scene.

string

provider_id

required

The logistics provider ID, which is the one filled in when placing an order or uploading a tracking number, must be consistent with it.

string

Example

{
  "country": "BR",
  "order_id": "577071607420326620",
  "external_tracking_url": "https://www.correios.com.br/rastreamento/BR3PL202609090001",
  "tracks": [
    {
      "action_code": 20201,
      "occur_time": 1788920100000,
      "description": "Package picked up by 3PL carrier",
      "failed_reason": "R110",
      "proof_url": "https://carrier-proof.example.com/proof/BR3PL202609090001",
      "location": {
        "country": "BR",
        "state": "SP",
        "city": "Campinas",
        "zip_code": "13010-000"
      },
      "tracking_no": "BR443310090002"
    }
  ],
  "provider_id": "7189579428429563650"
}

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

track_results

The trajectory node array, where the field in each element of the array indicates which trajectory it is. The code and message fields describe whether the trajectory has been received; if not, they represent the corresponding error code and error description.

Array<object>

object

action_code

The standard trajectory node code must belong to the allowlist. See the below action code.

integer format: int64

occur_time

Actual Trajectory Occurrence Time. Unix timestamp GMT (UTC+00:00). The unit is milliseconds.

integer format: int64

description

The original trajectory description of the caller.

string

code

The success or failure status of the trace corresponding to this action code, see the below error code

integer format: int64

message

The success or failure messages returned in the trace corresponding to this action code. Reasons of failure will be described in the message.

string

tracking_no

The waybill number used when placing an order. If there is no tracking code, fill in the invoice id instead. And it may change in split shipment, it may change in different track in this scene.

string

Example

{
  "code": 0,
  "data": {
    "track_results": [
      {
        "action_code": 32401,
        "occur_time": 1788920100012,
        "description": "Line-haul transport departed",
        "code": 0,
        "message": "Success",
        "tracking_no": "BR123456789"
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}