Skip to content
TikTok Shop Partner API

Get Package Detail

GET
/fulfillment/202309/packages/{package_id}

Returns information about a package, including handover time slot, tracking number, and shipping provider information.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
package_id
required
string

TikTok Shop package ID.

Query Parameters

Section titled “Query Parameters”
shop_cipher
required
string

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

Responses

Section titled “Responses”

200

Section titled “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
package_id

TikTok Shop package ID.

string
orders

The response list of TikTok Shop orders.

Array<object>
object
id

TikTok Shop order ID.

string
skus

[Deprecated]SKU information.

Array<object>
object
id

[Deprecated]SKU ID.

string
name

[Deprecated]SKU name.

string
image_url

[Deprecated]SKU image in order snapshot.

string
quantity

[Deprecated]SKU quantity.

integer format: int64
package_status

Possible values:

  • TO_FULFILL：Waiting for the merchant or warehouse to ship the package.
  • PROCESSING: Package has been arranged by seller. Waiting for carrier to collect the parcel.
  • FULFILLING: Package has been collected by carrier and in transit.
  • COMPLETED: Package has been delivered.
  • CANCELLED: Package has been canceled. Normally, the package is canceled due to the package being lost or damaged.
string
Allowed values: TO_FULFILL PROCESSING FULFILLING COMPLETED CANCELLED
package_sub_status

Package sub-status. Possible values:

  • CREATED: The package has been created.
  • ISSUE: Package allocation failed; contact platform support.
  • STOCKING: Platform verification is complete and the package is waiting for the seller to ship it.
  • RTSING: The shipping label is being purchased and the carrier result is pending.
  • HBW: For FBT orders only; the package has been created in the warehouse.
  • HBWING: For FBT orders only; the package is being created in the warehouse.
  • TSP_PENDING: Authorization for third-party service-provider fulfillment is pending.
  • RTS: The shipping label has been purchased and the seller can print it.
  • TTS: The carrier has picked up the package.
  • DELIVERED: The package has been delivered to the buyer.
  • SHIP_EXCEPTION: The package cannot be delivered, for example because it is damaged or lost. See ship_exception_reason for the detailed reason.
  • PART_DELIVERED_AND_EXCEPTION: Part of the package delivery completed and another part encountered a shipping exception.
  • CANCELLED: The package has been canceled.
string
Allowed values: CREATED ISSUE STOCKING RTSING HBW HBWING TSP_PENDING RTS TTS DELIVERED SHIP_EXCEPTION PART_DELIVERED_AND_EXCEPTION CANCELLED
ship_exception_reason

-PACKAGE_DAMAGAED -PACKAGE_LOST -RETURNED_TO_SHIPPER -PACKAGE_SCRAP

string
split_and_combine_tag

Possible values:

  • DEFAULT: The package has not undergone any combine or split operation.
  • COMBINE: The package has been consolidated with another order.
  • SPLIT: The order has been split into multiple orders.
string
Allowed values: DEFAULT COMBINE SPLIT
has_multi_skus

Whether there are multiple SKU IDs in a package.

boolean
note_tag

Possible values:

  • BUYER_UNNOTED: The order has not been noted by buyer.
  • BUYER_NOTED: The order has been noted by buyer.
string
Allowed values: BUYER_UNNOTED BUYER_NOTED
shipping_provider_name

Package shipping provider name.

string
shipping_provider_id

Package shipping provider ID.

string
shipping_type

Indicates who provides the shipping service. Possible values:

  • TIKTOK: Shipping service provided by TikTok. The seller should obtain a shipping label from TikTok.
  • SELLER: Seller provides shipping, including through a third-party fulfillment provider acting on the seller’s behalf.
string
Allowed values: TIKTOK SELLER
delivery_option_name

Delivery option name. For display purposes only.

string
delivery_option_id

Order delivery option ID. Delivery option ID is mapped to seller configured logistics templates ID.

string
tracking_number

Package tracking number.

string
last_mile_tracking_number

For cross-border order only. Cross-border order last mile tracking number.

string
pickup_slot

The carrier pickup time slot scheduled for the package.

object
start_time

The start of the package pickup time slot, as a Unix timestamp in seconds.

integer format: int64
end_time

The end of the package pickup time slot, as a Unix timestamp in seconds.

integer format: int64
create_time

Package creation time. Unix timestamp, in seconds.

integer format: int64
handover_method

Whether the package is delivered by pick up or drop off. Possible values:

  • PICKUP: A Logistics carrier will pickup the package(s) from the seller’s pickup address.
  • DROP_OFF: Seller will need to drop off the package(s) to a designated location.
string
Allowed values: PICKUP DROP_OFF
order_line_item_ids

The order line item ID contained in the package.

Array<string>
recipient_address

Recipient address and contact information. Returned personal information may be masked to protect the recipient’s privacy.

object
full_address

The recipient’s complete address, including geographic and detailed street-address information.

string
phone_number

The telephone number of the buyer. Please note, if this order use platform logistics, phone number will be desensitized.

string
name

The name of the recipient. Please note, if this order uses platform logistics, recipient name will be desensitized

string
postal_code

The postal code that can be used by seller for shipping (in the U.S, this refers to the ZIP code).

string
address_detail

The detailed street-address portion of the recipient’s address.

string
region_code

The country or region code of the recipient address.

string
address_line1

The first line of the street address

string
address_line2

The second line of the street address.

string
address_line3

The third line of the street address. Usually only for the Brazilian market.

string
address_line4

The fourth line of the street address. Usually only for the Brazilian market.

string
sender_address

The sender’s address and contact information. Sensitive fields may be masked.

object
full_address

The complete sender address, including geographic address components and address details.

string
phone_number

The telephone number of the sender.

string
name

The name of the sender.

string
postal_code

The postal code of the sender.

string
address_detail

The detailed street-address portion of the sender’s address.

string
region_code

Region code of the sender.

string
address_line1

The first line of the sender’s street address.

string
address_line2

The second line of the sender’s street address.

string
address_line3

The third line of the sender’s street address. Usually only for the Brazilian market.

string
address_line4

The fourth line of the sender’s street address. Usually only for the Brazilian market.

string
weight

The weight of the scheduled package.

object
value

The numerical value of the package weight.

string
unit

The unit of measurement for the package weight.

Available values:

  • GRAM
  • POUND
string
Allowed values: GRAM POUND
dimension

The dimensions of the scheduled package.

object
length

Package length.

string
width

Package width.

string
height

Package height.

string
unit

The unit of measurement for the package dimensions.

Available values:

  • CM
  • INCH
string
Allowed values: CM INCH
update_time

The time when the package was last updated, as a Unix timestamp in seconds.

integer format: int64
insurance

US only. Provides details of shipping insurance auto-enrolled during label purchase.

object
is_purchased

Whether insurance has been purchased for the package.

boolean
coverage_amount

The insurance coverage amount for the package. Units: USD.

string
is_claim_eligible

Whether the package is eligible for an insurance claim, based on eligible refund reasons.

boolean
claim_status

The insurance claim status. Available values:

  • NOT_STARTED: Claim has not been initiated for this package.
  • CLAIM_PENDING: Claim is currently under review.
  • APPROVED: Claim has been approved.
  • DECLINED: Claim has been declined.
string
Allowed values: NOT_STARTED CLAIM_PENDING APPROVED DECLINED
biz_extension_tags

Special tags for current package if any.

  • NON_MCF: whether this package was shipped as a MCF order while in fact it is not.
Array<string>
warehouse_id

Seller Warehouse id for this package

string
Example
{
  "code": 0,
  "data": {
    "package_id": "5433567853345",
    "orders": [
      {
        "id": "54335448533296",
        "skus": [
          {
            "id": "2729382476852921560",
            "name": "white,128g",
            "image_url": "https://p19-oec-sg.ibyteimg.com/tos-maliva-i-o3syd03w52-us/12345670c",
            "quantity": 5
          }
        ]
      }
    ],
    "package_status": "PROCESSING",
    "package_sub_status": "CREATED",
    "ship_exception_reason": "PACKAGE_LOST",
    "split_and_combine_tag": "SPLIT",
    "has_multi_skus": true,
    "note_tag": "BUYER_UNNOTED",
    "shipping_provider_name": "TT Virtual express",
    "shipping_provider_id": "6617675021119438849",
    "shipping_type": "TIKTOK",
    "delivery_option_name": "Shipped from seller\n",
    "delivery_option_id": "7091146663229654785",
    "tracking_number": "6617675021119438849",
    "last_mile_tracking_number": "6617675021119438849",
    "pickup_slot": {
      "start_time": 1635338186,
      "end_time": 1635338186
    },
    "create_time": 1635338186,
    "handover_method": "PICKUP",
    "order_line_item_ids": [
      "1729382476852921560"
    ],
    "recipient_address": {
      "full_address": "1*** Coleman Ave San Jose, CA 95110\n",
      "phone_number": "(+1)213-***-1234\n",
      "name": "Zay",
      "postal_code": "95110\n",
      "address_detail": "Unit one building 8\n",
      "region_code": "US",
      "address_line1": "TikTok 5800 bristol Pkwy\n",
      "address_line2": "Suite 100\n",
      "address_line3": "Suite 100\n",
      "address_line4": "Suite 100\n"
    },
    "sender_address": {
      "full_address": "1*** Coleman Ave San Jose, CA 95110",
      "phone_number": "(+1)213-***-1234\n",
      "name": "Zay",
      "postal_code": "95110",
      "address_detail": "Unit one building 8",
      "region_code": "US",
      "address_line1": "TikTok 5800 bristol Pkwy",
      "address_line2": "Suite 100",
      "address_line3": "Suite 100",
      "address_line4": "Suite 100"
    },
    "weight": {
      "value": "1.2",
      "unit": "GRAM"
    },
    "dimension": {
      "length": "1.2",
      "width": "0.2",
      "height": "0.03",
      "unit": "CM"
    },
    "update_time": 1635338186,
    "insurance": {
      "is_purchased": true,
      "coverage_amount": "200",
      "is_claim_eligible": true,
      "claim_status": "CLAIM_PENDING"
    },
    "biz_extension_tags": [
      "NON_MCF"
    ],
    "warehouse_id": "7317467398322308906"
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec