Batch Ship Packages

POST

/fulfillment/202309/packages/ship

Use this API to ship one or more packages in a single request. The API supports TikTok Shipping, Seller Shipping, and In-store Pickup.

• TikTok Shipping: Set each package’s handover_method to PICKUP for carrier pickup from the seller’s pickup address, or to DROP_OFF when the seller will drop it off at a designated location.
• Seller Shipping: Provide self_shipment.shipping_provider_id and self_shipment.tracking_number for each package. Obtain package IDs from Get Order Detail.
• In-store Pickup: Confirm shipment and notify the buyer that the order is ready for pickup.

A response with a top-level code of 0 can still contain package-specific failures. Check data.errors before treating every package as shipped.

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

Input list of packages you would like to batch ship.

Array<object>

object

id

required

Package ID.

string

handover_method

Possible values:

• PICKUP: A shipping provider will pickup the package(s) from the seller’s pickup address.
• DROP_OFF: The seller will need to drop off the package(s) at a designated location.

string

Allowed values: PICKUP DROP_OFF

pickup_slot

Package pickup time slot.

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

self_shipment

Only needed for seller shipping packages. Check the delivery_option field in Get Package Detail to see how to differentiate between TikTok shipping and seller shipping. Use the shipping_provider_id retrieved from the Get Shipping Providers API and upload the corresponding tracking number.

object

tracking_number

required

For packages with the SEND_BY_SELLER delivery option type (seller shipping), you must provide the package’s tracking number.

string

shipping_provider_id

required

For packages with the SEND_BY_SELLER delivery option type (seller shipping), you must provide the shipping provider information. Please use the Get Shipping Providers API to obtain the shipping_provider_id.

string

Example

{
  "packages": [
    {
      "id": "12321312312431",
      "handover_method": "PICKUP",
      "pickup_slot": {
        "start_time": 1623812664,
        "end_time": 1623812664
      },
      "self_shipment": {
        "tracking_number": "JX12345",
        "shipping_provider_id": "6617675021119438849"
      }
    }
  ]
}

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-specific errors for packages that could not be shipped. 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": "package in freeze status",
        "detail": {
          "package_id": "123123123123131"
        }
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}