Skip to content
TikTok Shop Partner API

Search Goods Info

POST
/fbt/202607/goods/search

Retrieves goods belonging to the merchant that match the specified filters and returns their IDs, names, goods-SKU relationships, merchant-declared measurements, warehouse-confirmed measurements, and other attributes. When more than one of goods_ids, product_ids, reference_codes, and sku_ids is provided, the API returns only goods that match all provided filter fields. If all four filters are empty or omitted, the API returns the merchant’s goods in descending creation-time order, limited by page_size.

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.

page_size
required
integer format: int64
>= 1 <= 100

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

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

Section titled “Request Body”
Media typeapplication/json
object
goods_ids

Fulfilled by TikTok goods IDs used to filter the results. Each ID must be a positive decimal string. Maximum: 100 IDs per request.

Array<string>
product_ids

TikTok Shop product IDs used to filter the results. Each ID must be a positive decimal string. Maximum: 100 IDs per request.

Array<string>
reference_codes

Merchant-defined goods reference codes used to filter the results. Maximum: 100 codes per request.

Array<string>
sku_ids

TikTok Shop SKU IDs used to filter the results. Each ID must be a positive decimal string. Maximum: 100 IDs per request.

Array<string>
Example
{
  "goods_ids": [
    "256080616234"
  ],
  "product_ids": [
    "256990616123"
  ],
  "reference_codes": [
    "SELLERSKU 123456"
  ],
  "sku_ids": [
    "256086568895"
  ]
}

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
next_page_token

An opaque token used to retrieve the next page. When this value is non-empty, pass it unchanged in the next request’s page_token. An empty string means there are no more pages.

string
total_count

The total number of goods that meet the query conditions.

integer format: int64
goods

A list of detailed information for Fulfilled by TikTok goods.

Array<object>
object
id

The identifier for goods generated by Fulfilled by TikTok system.

string
name

The goods name.

string
barcodes

A list of detailed information for goods barcodes.

Array<object>
object
code

The printable barcode for the goods.

string
type

The barcode type. Possible values:

  • UPC
  • EAN
  • GTIN
  • ASIN_OR_FNSKU
  • MERCHANT_SKU_ID
  • FBT_SPECIFIC_BARCODE
string
Allowed values: UPC EAN GTIN ASIN_OR_FNSKU MERCHANT_SKU_ID FBT_SPECIFIC_BARCODE
reference_code

The identifier for goods defined by merchant.

string
image_url

The goods image url.

string
merchant_declaration_info

The dimension and weight info input by merchant.

object
weight

The goods weight.

object
value

Weight value, up to three decimal places.

string
unit

Weight unit. Possible values:

  • MILLIGRAM
  • GRAM
  • KILOGRAM
  • POUND
  • OUNCE
string
Allowed values: MILLIGRAM GRAM KILOGRAM POUND OUNCE
dimension

The goods dimension.

object
width

Width value, up to three decimal places.

string
length

Length value, up to three decimal places.

string
height

Height value, up to three decimal places.

string
unit

Dimension unit. Possible values:

  • MILLIMETER
  • CENTIMETER
  • METER
  • FOOT
  • INCH
  • MICROMETER
string
Allowed values: MILLIMETER CENTIMETER METER FOOT INCH MICROMETER
warehouse_confirmation_info

Dimension and weight information verified by the warehouse during the goods’ first inbound. Returned only when at least one warehouse-confirmed weight, length, width, or height value is available. If this object is omitted, no warehouse-confirmed measurement is available in this response.

object
weight

The goods weight.

object
value

Weight value, up to three decimal places.

string
unit

Weight unit. Possible values:

  • MILLIGRAM
  • GRAM
  • KILOGRAM
  • POUND
  • OUNCE
string
Allowed values: MILLIGRAM GRAM KILOGRAM POUND OUNCE
dimension

The goods dimension.

object
width

Width value verified by warehouse, up to three decimal places.

string
length

Length value verified by warehouse, up to three decimal places.

string
height

Height value verified by warehouse, up to three decimal places.

string
unit

Dimension unit. Possible values:

  • MILLIMETER
  • CENTIMETER
  • METER
  • FOOT
  • INCH
  • MICRO
string
Allowed values: MILLIMETER CENTIMETER METER FOOT INCH MICRO
skus

A list of Stock Keeping Units (SKUs) infomation matched with current FBT goods.

Array<object>
object
id

The identifier for SKU generated by TikTok Shop system.

string
name

The SKU name.

string
image_url

The TikTok Shop SKU image url.

string
product

The TikTok Shop product matched with current Fulfilled by TikTok goods.

object
id

The identifier for product generated by TikTok Shop system.

string
name

The TikTok Shop product name.

string
image_url

The Tiktok Shop product image url.

string
regions

The regions where the SKU is being sold, represented by region codes in the two-character ISO 3166-1 alpha-2 format.

Array<string>
matched

Indicates that the SKU is matched to the current Fulfilled by TikTok goods. Entries in skus are matched relations, so this value is always true.

boolean
lot_expiration_info

The goods lot control and expiration managment information.

object
is_lot_control

A flag indicating whether the goods is under lot control. True: Under lot control. False: Not under lot control. Note: Lot code and expiration date management information is mandatory for these product categories according to Fulfilled by TikTok guidelines.

boolean
is_expiration_management

A flag indicating whether the goods is under expiration managment. True: Under expiration managment. False: Not under expiration managment.

boolean
shelf_life_days

The goods shelf life days input by merchant, represent the total number of days the product remains usable or sellable from the time it is manufactured until its expiration.

integer format: int64
inbound_cutoff_days

The goods inbound cutoff days before expiration, represent the time period before the product’s expiration when the warehouse will no longer accept inbound shipments.

integer format: int64
expiration_alert_days

The goods alert days before expired, represent the period of time before platform send expiration reminder alerts to the merchant.

integer format: int64
sales_cutoff_days

The goods sales cut off days before expired, represent the period of time before expiration in which the goods will no longer be available for sale.

integer format: int64
handling_method

The handling method for expired inventory. Possible values:

  • STORE_UNITS: Move the units to defective inventory.
  • RETURN_TO_SELLER: Return the units to the seller.
  • DISPOSE: Dispose of the units.
string
Allowed values: STORE_UNITS RETURN_TO_SELLER DISPOSE
is_hazmat

Whether is hazmat goods

boolean
hazmat_info

Hazardous-material details. Returned only when is_hazmat is true. The subtype object depends on hazmat_type: battery_extra_info for BATTERY, flammable_liquids_extra_info for FLAMMABLE_LIQUID, and aerosol_extra_info for AEROSOLS. MAGNETIZED does not include a subtype object.

object
hazmat_type

Hazardous goods type Possible values: -MAGNETIZED -BATTERY -FLAMMABLE_LIQUID -AEROSOLS

string
Allowed values: MAGNETIZED BATTERY FLAMMABLE_LIQUID AEROSOLS
battery_extra_info

Additional battery information for hazmat goods.

object
battery_type

Battery type Possible values: LITHIUM_ION LITHIUM_METAL OTHER

string
battery_packaging_type

Battery packaging type. Possible values:

  • STANDALONE
  • IN_EQUIPMENT
  • WITH_EQUIPMENT
  • OTHER
string
Allowed values: STANDALONE IN_EQUIPMENT WITH_EQUIPMENT OTHER
total_battery_weight

Total battery weight in the unit specified by total_battery_weight_unit.

string
total_battery_weight_unit

Unit for total_battery_weight. Possible value: GRAM.

string
total_battery_capacity

Total battery capacity in the unit specified by total_battery_capacity_unit.

string
battery_count_per_package

Per package battery count

string
is_need_un_38_3_test

UN38.3 testing ensures that batteries meet specific safety criteria. Please send the report in the field if it’s not included in the MSDS.

boolean
un_38_3_test_file_url

UN38.3 testing file URL

string
total_battery_capacity_unit

Unit for total_battery_capacity, such as WATT_HOURS.

string
flammable_liquids_extra_info

Flammable liquids info

object
flammable_liquids_type

Flammable liquid type, possible values -PAINT -PERFUMERY -ALCOHOLIC -OTHER

string
Allowed values: PAINT PERFUMERY ALCOHOLIC OTHER
flammable_liquids_volume

Volume of flammable liquid in the unit specified by volume_unit.

string
volume_unit

Unit for flammable_liquids_volume, such as MILLILITER.

string
aerosol_extra_info

Aerosol info

object
volume

Aerosol volume. Required when hazmat_type is AEROSOLS. The value must be a numeric string greater than 0.

string
volume_unit

Aeroslo volume unit

string
dg_class

Hazmat class Possible values: -CLASS_2 -CLASS_3 -CLASS_9

string
Allowed values: CLASS_2 CLASS_3 CLASS_9
dg_uncode

UN identifier for the hazardous substance. Standard UN values use the UN prefix followed by four digits; OTHER is also supported. Possible values:

  • UN2807
  • UN3480
  • UN3090
  • UN3481
  • UN3091
  • UN1263
  • UN1266
  • UN3065
  • OTHER
string
Allowed values: UN2807 UN3480 UN3090 UN3481 UN3091 UN1263 UN1266 UN3065 OTHER
msds_file_url

Material safety data sheet of the hazmat goods to support review the goods’ safety compliance in FBT

string
sioc_approval_status

SIOC-specific approval status. This field is returned when is_sioc is true and an SIOC approval status is available. Possible values:

  • SIOC_APPROVAL_STATUS_INVALID
  • SIOC_APPROVAL_STATUS_INIT
  • SIOC_APPROVAL_STATUS_UNDER_REVIEW
  • SIOC_APPROVAL_STATUS_APPROVE
  • SIOC_APPROVAL_STATUS_REJECT
string
Allowed values: SIOC_APPROVAL_STATUS_INVALID SIOC_APPROVAL_STATUS_INIT SIOC_APPROVAL_STATUS_UNDER_REVIEW SIOC_APPROVAL_STATUS_APPROVE SIOC_APPROVAL_STATUS_REJECT
hazmat_approval_status

FBT fulfillment approval status. This field is returned for goods that are hazardous materials or managed as Ships in Own Container (SIOC). Possible values:

  • APPROVAL_STATUS_INVALID
  • APPROVAL_STATUS_INIT
  • APPROVAL_STATUS_UNDER_REVIEW
  • APPROVAL_STATUS_FULFILLABLE
  • APPROVAL_STATUS_UNFULFILLABLE
string
Allowed values: APPROVAL_STATUS_INVALID APPROVAL_STATUS_INIT APPROVAL_STATUS_UNDER_REVIEW APPROVAL_STATUS_FULFILLABLE APPROVAL_STATUS_UNFULFILLABLE
bulky_item_attribute

Bulky item info

object
is_bulky_item

Whether the goods is_bulky_item

boolean
is_bulky_item_accessories

Whether the goods is bulky accessories

boolean
goods_safety_attributes

Safety attribute info

object
is_fragile

Where fragile

boolean
is_liquid

Whether the goods are liquid.

boolean
is_sharp

Where sharp

boolean
is_sioc

Whether sioc

boolean
sioc_attribute

Sioc info

object
sioc_files

Sioc files

Array<object>
object
sioc_certification_url

Sico attachment url

string
sioc_file_type

Sioc attachment type:

  • PHOTO
  • DOCUMENT
  • DROP_TEST_VIDEO
string
Example
{
  "code": 0,
  "data": {
    "next_page_token": "cGFnZV9udW1iZXI9Mg==",
    "total_count": 123,
    "goods": [
      {
        "id": "86533997569",
        "name": "water1.0",
        "barcodes": [
          {
            "code": "014673829105",
            "type": "UPC"
          }
        ],
        "reference_code": "abc32323",
        "image_url": "https://example.com/fbt/goods-image.jpg",
        "merchant_declaration_info": {
          "weight": {
            "value": "1.122",
            "unit": "GRAM"
          },
          "dimension": {
            "width": "1.122",
            "length": "2.122",
            "height": "3.122",
            "unit": "CENTIMETER"
          }
        },
        "warehouse_confirmation_info": {
          "weight": {
            "value": "1",
            "unit": "GRAM"
          },
          "dimension": {
            "width": "1",
            "length": "2.5",
            "height": "3",
            "unit": "CENTIMETER"
          }
        },
        "skus": [
          {
            "id": "1729439634328225260",
            "name": "Testcase SKU",
            "image_url": "https://example.com/fbt/sku-image.jpg",
            "product": {
              "id": "1729439631253210604",
              "name": "Testcase_xd2.0_test_goods",
              "image_url": "https://example.com/fbt/product-image.jpg"
            },
            "regions": [
              "US"
            ],
            "matched": true
          }
        ],
        "lot_expiration_info": {
          "is_lot_control": true,
          "is_expiration_management": true,
          "shelf_life_days": 12,
          "inbound_cutoff_days": 90,
          "expiration_alert_days": 60,
          "sales_cutoff_days": 20,
          "handling_method": "DISPOSE"
        },
        "is_hazmat": false,
        "hazmat_info": {
          "hazmat_type": "MAGNETIZED",
          "battery_extra_info": {
            "battery_type": "LITHIUM_ION",
            "battery_packaging_type": "STANDALONE",
            "total_battery_weight": "1",
            "total_battery_weight_unit": "GRAM",
            "total_battery_capacity": "1",
            "battery_count_per_package": "2",
            "is_need_un_38_3_test": false,
            "un_38_3_test_file_url": "https://example.com/fbt/msds-report.pdf",
            "total_battery_capacity_unit": "WATT_HOURS"
          },
          "flammable_liquids_extra_info": {
            "flammable_liquids_type": "PAINT",
            "flammable_liquids_volume": "1",
            "volume_unit": "MILLILITER"
          },
          "aerosol_extra_info": {
            "volume": "1",
            "volume_unit": "MILLILITER"
          },
          "dg_class": "CLASS_2",
          "dg_uncode": "UN1266",
          "msds_file_url": "https://example.com/fbt/msds-report.pdf"
        },
        "sioc_approval_status": "SIOC_APPROVAL_STATUS_APPROVE",
        "hazmat_approval_status": "APPROVAL_STATUS_UNDER_REVIEW",
        "bulky_item_attribute": {
          "is_bulky_item": false,
          "is_bulky_item_accessories": false
        },
        "goods_safety_attributes": {
          "is_fragile": false,
          "is_liquid": false,
          "is_sharp": false
        },
        "is_sioc": false,
        "sioc_attribute": {
          "sioc_files": [
            {
              "sioc_certification_url": "https://example.com/fbt/sioc-certification.jpg",
              "sioc_file_type": "PHOTO"
            }
          ]
        }
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec