Update Package Delivery Status

POST

/fulfillment/202309/packages/deliver

Use this API to report delivery outcomes for SOF (Seller Own Fleet) packages or confirm O2O (Store Pickup) package delivery. For SOF, use DELIVERY_SUCCESS, DELIVERY_FAILED, or UPDATE_POD. For O2O, use DELIVERY_SUCCESS and provide the pickup verification code. Only sellers using SOF or O2O can use this API. This API is available only in the SEA region.

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

packages

required

The packages to update. Provide at least one package.

Array<object>

object

id

required

The package ID.

string

delivery_type

required

Delivery status of the package. Possible values for in-store pick up:

• DELIVERY_SUCCESS: The package has been successfully delivered. Possible values for SOF (Seller Own Fleet):
• DELIVERY_SUCCESS: The package has been successfully delivered.
• DELIVERY_FAILED: The package could not be delivered successfully.
• UPDATE_POD: Updates the attachment for a package that has already been delivered.

string

Allowed values: DELIVERY_SUCCESS DELIVERY_FAILED UPDATE_POD

fail_delivery_reason

Delivery failure reasons.

When delivery_type = DELIVERY_FAILED, this field is required. For other delivery types, this field is not required.

Possible values:

• INVALID_ADDRESS: The buyer shipping address is invalid.
• UNABLE_RECEIVE: The buyer is currently unable to receive the delivery.
• UNABLE_CONTACT_BUYER: Unable to contact the buyer.
• BUYER_REFUSED: The buyer has refused to receive the product.
• DELAY_DELIVERY: Delay in delivery.
• PACKAGE_LOST: The package is lost.
• PACKAGE_DAMAGE: The package is damaged.
• FORCE_MAJEURE: An unforeseeable event of force majeure has occurred.
• OTHER: Other reason.

string

Allowed values: INVALID_ADDRESS UNABLE_RECEIVE UNABLE_CONTACT_BUYER BUYER_REFUSED DELAY_DELIVERY PACKAGE_LOST PACKAGE_DAMAGE FORCE_MAJEURE OTHER

file_type

Attachment type:

• IMG
• PDF

string

file_url

Attachment URL. The seller can use the Upload Delivery File and Upload Delivery Image APIs to generate the URL. The attachment will be used by TikTok Shop to verify the package delivery.

string

verification_code

The verification code required for order pickup.

string

Example

{
  "packages": [
    {
      "id": "11529598723402",
      "delivery_type": "DELIVERY_SUCCESS",
      "fail_delivery_reason": "INVALID_ADDRESS",
      "file_type": "IMG",
      "file_url": "https://tiktok.shopcenter.cn/file/CWvBsBZ9mhbMiHtmbZecKshon6f?table=tblTW",
      "verification_code": "123456"
    }
  ]
}

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

errors

Package-level failures from the batch request. Each entry identifies the affected package and contains the returned failure code and message fields. Check this list even when the top-level response code is 0.

Array<object>

object

code

The failure reason code.

integer format: int64

message

The failure reason message.

string

detail

Error detail.

object

package_id

Package ID.

string

Example

{
  "code": 0,
  "data": {
    "errors": [
      {
        "code": 10007014,
        "message": "order not in sof service",
        "detail": {
          "package_id": "1231231231231"
        }
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}