Skip to content
TikTok Shop Partner API

Get FBT Inbound Order Details

GET
/fbt/202602/inbound_orders

Retrieves details for the specified FBT inbound orders, including planned and actual receiving information and status history. Set include_carton_details to true to request carton dimensions and item quantities.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
shop_cipher
required
string

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

order_ids
required
Array<string>

The list of numeric identifiers of the inbound orders to fetch information for.
Note: Provide the numeric sequence only; do not include the “IBR” prefix (e.g., use 123456 instead of IBR123456). There is a limit of 10 orders to be fetched in each request.

Only orders that are found and accessible to the current seller are returned. Missing or inaccessible order IDs are omitted from the response; the request fails if none of the requested orders can be returned.

You can get the value in data.inbound_order_id in Inbound FBT order status change webhook or in data.inventory_records.order.id in the response of Search FBT Inventory Record.

include_carton_details
boolean

A boolean flag that determines whether the response should include granular information for each individual carton within the shipment.

Note: When set to true, the response will include the carton_details field. If set to false or omitted, this field will be excluded from the response payload to optimize performance.

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
inbound_orders

A list of inbound order detail information.

Array<object>
object
order_id

The numeric identifier for inbound order in Fulfilled by TikTok system.

string
order_id_string

The string identifier for inbound order in Fulfilled by TikTok system.

string
order_plan_id

Plan identifier for the inbound order.

string
merchant

Information regarding the merchant who owns the order.

object
id

The identifier of the merchant in Fulfilled by TikTok system.

string
name

Name of the Fulfilled by TikTok merchant.

string
create_time

Unix seconds timestamp when the inbound order was created.

integer format: int64
ship_time

Unix seconds timestamp when the inbound order was shipped.

integer format: int64
expected_arrival_time

Unix seconds timestamp of the expected arrival time provided by merchant.

integer format: int64
actual_arrival_time

Unix seconds timestamp of the actual arrival time of the inbound order.

integer format: int64
warehouse

Warehouse information.

object
fbt_warehouse_id

The identifier for warehouse generated by Fulfilled by TikTok system.

string
business_warehouse_ids

The business identifier for warehouse generated by TikTok Shop system, correlated with the fbt_warehouse_id.

Array<string>
name

The Fulfilled by TikTok warehouse name.

string
type

Type of warehouse associated with the inbound order.

Possible values:

  • HUB
  • FC (Fulfillment Center)
string
Allowed values: HUB FC
status_logs

Inbound order operation-history entries derived from at most 200 source status records. This list may be incomplete, and this operation does not provide a cursor for retrieving additional status records.

Array<object>
object
operate_time

The time when the inbound order is processed by the merchant or warehouses, represented as a Unix timestamp in seconds.

integer format: int64
new_status

The order status in Fulfilled by TikTok (FBT) warehouse after this operation.

Possible values:

  • WORKING
  • READY_TO_SHIP
  • TO_BE_RECEIVED
  • ARRIVED_HUB
  • INTERNAL_TRANSFER
  • RECEIVING
  • PARTIALLY_RECEIVED
  • RECEIVED
  • CANCELLED
  • DELIVERED
string
Allowed values: WORKING READY_TO_SHIP TO_BE_RECEIVED ARRIVED_HUB INTERNAL_TRANSFER RECEIVING PARTIALLY_RECEIVED RECEIVED CANCELLED DELIVERED
previous_status

The order status in Fulfilled by TikTok (FBT) warehouse before this operation.

Possible values:

  • WORKING
  • READY_TO_SHIP
  • TO_BE_RECEIVED
  • ARRIVED_HUB
  • INTERNAL_TRANSFER
  • RECEIVING
  • PARTIALLY_RECEIVED
  • RECEIVED
  • CANCELLED
  • DELIVERED
string
Allowed values: WORKING READY_TO_SHIP TO_BE_RECEIVED ARRIVED_HUB INTERNAL_TRANSFER RECEIVING PARTIALLY_RECEIVED RECEIVED CANCELLED DELIVERED
operator

The unique identifier or name of the user or system entity that performed the status change.

string
logistic_info_list

List of logistics information tied to the order. Only populated for small-parcel inbound orders.

Array<object>
object
provider_name

Name of the logistics service provider

Possible values:

  • FEDEX (Federal Express)
  • UPS (United Parcel Service)
  • DHL (DHL Express)
  • USPS (United States Postal Service)
  • OTHER (All other logistics providers)
string
Allowed values: FEDEX UPS DHL USPS OTHER
waybill_number

The tracking number for the current inbound shipment with the carrier.

string
related_number

Carton number tied to the logistics information.

string
carton_details

Detailed carton information for the inbound order. Only populated if include_carton_details is passed as true in the request.

Array<object>
object
carton_no

Carton number.

string
carton_type

Whether this carton is single-SKU or multi-SKU.

Possible values:

  • SINGLE_SKU
  • MULTI_SKU
string
Allowed values: SINGLE_SKU MULTI_SKU
box_measurements

Carton measurement.

object
weight

Carton weight.

string
weight_unit

The unit used for the carton’s weight value.

Possible values:

  • KILOGRAM (kg)
  • GRAM (g)
  • MILLIGRAM (mg)
  • POUNDS (lbs)
  • OUNCE (oz)
string
Allowed values: KILOGRAM GRAM MILLIGRAM POUNDS OUNCE
width

Carton width.

string
height

Carton height.

string
length

Carton length.

string
length_unit

The unit used for the carton’s length, width, and height values.

Possible values:

  • METER (m)
  • CENTIMETER (cm)
  • MILLIMETER (mm)
  • FOOT (ft)
  • MICRON (μm)
  • INCH (in)
string
Allowed values: METER CENTIMETER MILLIMETER FOOT MICRON INCH
items

List of items in this carton.

Array<object>
object
goods_id

Identifier for goods within the Fulfilled by TikTok system.

string
quantity

The number of units of the goods in this carton.

integer format: int64
inbound_goods_lot_receive_item_details

A detailed breakdown of planned versus actual receiving information, segmented by item, lot number, and expiration date.

Array<object>
object
goods_id

The unique numeric identifier of the goods within Fulfilled by TikTok.

string
lot_code

The batch or lot number assigned by the manufacturer for this group of items. This field is non-empty only for goods with lot code management.

string
expiration_time

The expiration date of the items in this lot, represented as a Unix timestamp in seconds. This value is non-zero only for goods with expiration-date management.

integer format: int64
planned_count

The total quantity of this specific lot expected to be received as part of the inbound order.

integer format: int64
normal_received_count

The quantity of items received at fulfillment centers in sellable (good) condition for this lot. If the inbound order is sent to a hub, this value will only be updated when the goods are subsequently transferred to the fulfillment center.

integer format: int64
defective_received_count

The quantity of items received in a damaged or unsellable state.

integer format: int64
total_received_count

The sum of both normal_received_count and defective_received_count.

integer format: int64
Example
{
  "code": 0,
  "data": {
    "inbound_orders": [
      {
        "order_id": "5766071177167344427",
        "order_id_string": "IBR5766071177167344427",
        "order_plan_id": "5766071177167345050",
        "merchant": {
          "id": "493493403043",
          "name": "ExampleCompany"
        },
        "create_time": 1773778751,
        "ship_time": 1773778751,
        "expected_arrival_time": 1773778751,
        "actual_arrival_time": 1773778751,
        "warehouse": {
          "fbt_warehouse_id": "121219993203023",
          "business_warehouse_ids": [
            "121219993209983"
          ],
          "name": "TikTok Warehouse",
          "type": "FC"
        },
        "status_logs": [
          {
            "operate_time": 1715398048,
            "new_status": "RECEIVED",
            "previous_status": "PARTIALLY_RECEIVED",
            "operator": "Warehouse"
          }
        ],
        "logistic_info_list": [
          {
            "provider_name": "UPS",
            "waybill_number": "889042812410",
            "related_number": "C0001"
          }
        ],
        "carton_details": [
          {
            "carton_no": "C0001",
            "carton_type": "SINGLE_SKU",
            "box_measurements": {
              "weight": "5",
              "weight_unit": "KILOGRAM",
              "width": "6",
              "height": "7",
              "length": "8",
              "length_unit": "METER"
            },
            "items": [
              {
                "goods_id": "7603596185",
                "quantity": 10
              }
            ]
          }
        ],
        "inbound_goods_lot_receive_item_details": [
          {
            "goods_id": "7603596185",
            "lot_code": "LOT-2024-XP9",
            "expiration_time": 1735689600,
            "planned_count": 100,
            "normal_received_count": 98,
            "defective_received_count": 2,
            "total_received_count": 100
          }
        ]
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec