Search Package

POST

/fulfillment/202309/packages/search

Retrieve packages, optionally filtered by creation time, update time, or package status.

Authorizations

• accessToken

Parameters

Query Parameters

shop_cipher

required

string

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

page_size

required

integer format: int64

>= 1 <= 50

The number of results to be returned per page. Valid range: [1-50].

sort_field

string

Allowed values: create_time update_time order_pay_time

The returned results will be sorted by the specified field. Default: create_time Possible values:

• create_time
• update_time
• order_pay_time

Specify the order for sorting the returned results by using the sort_order parameter.

sort_order

string

Allowed values: ASC DESC

The sort order for the sort_field parameter. Default: DESC Possible values:

• ASC: Ascending order
• DESC: Descending order

page_token

string

An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the next_page_token from a previous response. It is not needed for the first page.

Request Body

Media typeapplication/json

object

create_time_ge

Filter packages to those created at or after the specified time. Unix timestamp, in seconds.

integer format: int64

create_time_lt

Filter packages to those created before the specified time. Unix timestamp, in seconds.

integer format: int64

update_time_ge

Filter packages to those updated at or after the specified time. Unix timestamp, in seconds.

integer format: int64

update_time_lt

Filter packages to those updated before the specified time. Unix timestamp, in seconds.

integer format: int64

package_status

Possible values:

• TO_FULFILL
• 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

Example

{
  "create_time_ge": 1623812664,
  "create_time_lt": 1623812664,
  "update_time_ge": 1623812664,
  "update_time_lt": 1623812664,
  "package_status": "PROCESSING"
}

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

next_page_token

An opaque token used to retrieve the next page of a paginated result set. If this value is non-empty, provide it in the page_token parameter of the next request. If this value is empty, stop pagination.

string

total_count

The number of packages that meet the query conditions.

integer format: int64

packages

The response list of packages.

Array<object>

object

id

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

create_time

Package creation time. Unix timestamp, in seconds.

integer format: int64

update_time

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

integer format: int64

status

Possible values:

• TO_FULFILL
• 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

tracking_number

Package tracking number.

string

shipping_provider_name

Package shipping provider.

string

shipping_provider_id

Package shipping provider ID.

string

order_line_item_ids

The order line item ID contained in the package.

Array<string>

Example

{
  "code": 0,
  "data": {
    "next_page_token": "6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmq/N5M1kHYcZmtRyv9aVrNv65W7Q6tFA",
    "total_count": 221,
    "packages": [
      {
        "id": "577828281214600000",
        "orders": [
          {
            "id": "577828281214600000",
            "skus": [
              {
                "id": "577828281214883345",
                "name": "white,128g",
                "image_url": "https://p19-oec-sg.ibyteimg.com/tos-maliva-i-o3syd03w52-us/12345670",
                "quantity": 5
              }
            ]
          }
        ],
        "create_time": 1635338186,
        "update_time": 1635338186,
        "status": "PROCESSING",
        "tracking_number": "6617675021119438849",
        "shipping_provider_name": "TT Virtual express",
        "shipping_provider_id": "6617675021119438849",
        "order_line_item_ids": [
          "1729382476852921560"
        ]
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}