Search FBT Inventory

POST

/fbt/202408/inventory/search

This API is used to retrieve detailed inventory information for goods and matched SKUs, including sellable inventory, reserved inventory, unsellable inventory, and in-transit inventory at the warehouse level.

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 <= 100

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

page_token

string

Pagination page token. It should be empty for the first page.

Request Body

Media typeapplication/json

object

goods_ids

The identifiers for goods generated by the Fulfilled by TikTok system. Maximum: 100 goods IDs per request. If specified, only inventory information for those goods is returned. If both goods_ids and sku_ids are omitted, all goods with non-zero inventory are returned.

Do not provide goods_ids and sku_ids in the same request. Both fields may be omitted.

Array<string>

fbt_warehouse_ids

The identifiers of warehouses generated by the Fulfilled by TikTok system. Specify up to 100 warehouse IDs to return inventory records only for subscribed warehouses that match those IDs. If omitted or empty, inventory records from all warehouses subscribed by the merchant are returned.

Array<string>

<= 100 items

sku_ids

TikTok Shop SKU identifiers used to select goods matched to those SKUs. Maximum: 100 SKU IDs per request. Do not provide sku_ids and goods_ids in the same request; both fields may be omitted. For each matched goods record, the returned goods.skus list contains the SKU inventory supplied for that goods record and is not restricted to the requested SKU IDs.

Array<string>

Example

{
  "goods_ids": [
    "256080616234",
    "2231616264"
  ],
  "fbt_warehouse_ids": [
    "7232382932030232"
  ],
  "sku_ids": [
    "256080616234"
  ]
}

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. Provide this value in the page_token parameter of your next request. An empty next_page_token means there are no more pages.

string

total_count

The total number of warehouse-goods inventory records that match the applied filters.

integer format: int64

inventory

A list of inventory records. Each item represents one goods item at one Fulfilled by TikTok warehouse and can include the associated SKU inventory breakdown.

Array<object>

object

goods

The reference used to track products and SKUs within Fulfilled by TikTok’s network.

object

id

The identifier for goods generated by Fulfilled by TikTok system.

string

reference_code

The identifier for goods defined by the merchant, commonly used to reference the ID from the merchant’s other order management systems.

string

name

The goods name.

string

skus

A list of inventory information for Stock Keeping Units (SKUs) matched with current Fulfilled by TikTok goods.

Array<object>

object

id

The identifier for SKU generated by TikTok Shop system.

string

on_hand_detail

The inventory information of SKU physically in the warehouse, excluding those in transit or broken.

object

total_quantity

The total number of units for current SKU, consist of available_quantity and reserved_quantity.

integer format: int64

available_quantity

The number of units available for sale. Note: The number does not include reserved units.

integer format: int64

reserved_quantity

The number of units reserved for customer orders or return to supplier shipment.

integer format: int64

fbt_warehouse_id

The identifier for warehouse generated by Fulfilled by TikTok system.

string

in_transit_quantity

The number of goods units currently en route to the warehouse. The inventory includes inbound replenishments, customer returns, unsuccessful delivery returns, etc.

integer format: int64

on_hand_detail

The current-in-warehouse inventory detail for the goods.

object

total_quantity

The total on-hand quantity for the goods at the Fulfilled by TikTok warehouse, excluding in-transit inventory.

integer format: int64

available_quantity

The number of units available for sale. Note: The number does not include reserved units.

integer format: int64

reserved_quantity

The number of units reserved for customer orders or return to supplier shipment.

integer format: int64

unfulfillable_quantity

The number of defective units in the warehouse.

integer format: int64

Example

{
  "code": 0,
  "data": {
    "next_page_token": "cGFnZV9udW1iZXI9Mg==",
    "total_count": 22113,
    "inventory": [
      {
        "goods": {
          "id": "69167899745030",
          "reference_code": "water01",
          "name": "100ml water",
          "skus": [
            {
              "id": "73243612345",
              "on_hand_detail": {
                "total_quantity": 20,
                "available_quantity": 5,
                "reserved_quantity": 15
              }
            }
          ]
        },
        "fbt_warehouse_id": "7232382932030232",
        "in_transit_quantity": 10,
        "on_hand_detail": {
          "total_quantity": 20,
          "available_quantity": 5,
          "reserved_quantity": 15,
          "unfulfillable_quantity": 0
        }
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}