Skip to content
TikTok Shop Partner API

Create FBT Goods

POST
/fbt/202607/goods/create_goods

Create FBT goods records and link each record to a TikTok Shop SKU. Request-level errors can be returned before per-item results are populated. When create_result_info.create_result_list contains entries, correlate them by tts_sku_id, check is_success for each returned item, read fail_reason for failures, and use tts_goods_id for successes.

The request supports dimensions and weight, return handling, hazardous-material, shelf-life, SIOC, bulky-item, and safety attributes.

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.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
create_goods_dto_list
required

List of goods records to create.

Array<object>
object
tts_sku_id
required

Identifier for Stock Keeping Unit (SKU) generated by TikTok Shop system

string
create_goods_type
required

Type of create-goods operation. Current supported value: CREATE_AND_BIND.

string
goods_name
required

Name of the goods. Maximum length: 255 characters.

string
<= 255 characters
goods_image_url
required

Image URL for the goods.

string
reference_code

Reference code for the goods. Maximum length: 50 characters.

string
<= 50 characters
barcode_infos

Barcodes for the goods. For each goods record, provide at most one UPC, EAN, or GTIN in total, at most five ASIN_OR_FNSKU values, and at most five MERCHANT_SKU_ID values.

Array<object>
object
barcode_type

Type of barcode provided for the goods, such as UPC.

string
barcode_value

Barcode value. UPC must contain 8 or 12 digits; EAN must contain 8 or 13 digits; and GTIN must contain 8, 12, 13, or 14 digits. UPC, EAN, and GTIN values must have a valid checksum. ASIN_OR_FNSKU must contain 10 uppercase letters or digits and start with B or X. MERCHANT_SKU_ID must contain 1 to 32 printable ASCII characters with no whitespace.

string
return_handling_method
required

Return handling method for the FBT customer return service. The default value will be Restock sellable, Dispose unsellable. Possible values:

  • COLLECT_RETURN_UNITS
  • RESTOCK_SELLABLE_COLLECT_UNSELLABLE
  • RESTOCK_SELLABLE_DISPOSE_UNSELLABLE
  • DISPOSAL_WITHOUT_INSPECTION
  • RETURN_WITHOUT_INSPECTION
  • RESTOCK_SELLABLE_RETURN_UNSELLABLE
string
Allowed values: COLLECT_RETURN_UNITS RESTOCK_SELLABLE_COLLECT_UNSELLABLE RESTOCK_SELLABLE_DISPOSE_UNSELLABLE DISPOSAL_WITHOUT_INSPECTION RETURN_WITHOUT_INSPECTION RESTOCK_SELLABLE_RETURN_UNSELLABLE
dimension_and_weight_base_info
required

Dimensions and weight for the goods. weight_value, length_value, width_value, and height_value must each be a numeric string greater than 0.

object
weight_value
required

Weight of the goods in the specified weight_unit.

string
length_value
required

Length of the goods in the specified dimension_unit.

string
width_value
required

Width of the goods in the specified dimension_unit.

string
height_value
required

Height of the goods in the specified dimension_unit.

string
weight_unit
required

Weight unit. Possible values: MILLIGRAM (mg), GRAM (g), KILOGRAM (kg), POUND (lb), OUNCE (oz).

string
dimension_unit
required

Dimension unit. Possible values: MILLIMETER (mm), CENTIMETER (cm), METER (m), FOOT (ft), INCH (in).

string
is_hazmat
required

Whether is hazmat goods

boolean
hazmat_info

Hazardous-material details. Required when is_hazmat is true. For hazmat_type BATTERY, FLAMMABLE_LIQUID, or AEROSOLS, provide battery_extra_info, flammable_liquids_extra_info, or aerosol_extra_info, respectively.

object
hazmat_type
required

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

string
Allowed values: MAGNETIZED BATTERY FLAMMABLE_LIQUID AEROSOLS
battery_extra_info

Battery details for goods with hazmat_type set to BATTERY. total_battery_weight must be greater than 0. When battery_packaging_type is STANDALONE, battery_count_per_package must be greater than 0. When is_need_un_38_3_test is true, provide un_38_3_test_file_url.

object
battery_type
required

Battery type Possible values: LITHIUM_ION LITHIUM_METAL OTHER

string
battery_packaging_type
required

Battery packaging type. Possible values:

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

Total battery weight in the unit specified by total_battery_weight_unit.

string
total_battery_weight_unit
required

Unit for total_battery_weight. Possible value: GRAM.

string
total_battery_capacity
required

Total battery capacity in the unit specified by total_battery_capacity_unit.

string
total_battery_capacity_unit
required

Unit for total_battery_capacity, such as WATTHOUR.

string
is_need_un_38_3_test
required

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
battery_count_per_package

Per package battery count

string
flammable_liquids_extra_info

Flammable-liquid details for goods with hazmat_type set to FLAMMABLE_LIQUID. flammable_liquids_volume must be a numeric string greater than 0.

object
flammable_liquids_type
required

Flammable-liquid type. Possible values:

  • PAINT
  • PERFUMERY
  • ALCOHOLIC
  • OTHER
string
Allowed values: PAINT PERFUMERY ALCOHOLIC OTHER
flammable_liquids_volume
required

Volume of flammable liquid in the unit specified by volume_unit.

string
volume_unit

Unit for flammable_liquids_volume, such as MILLILITERS.

string
dg_class
required

Hazmat class Possible values: -CLASS_2 -CLASS_3 -CLASS_9

string
Allowed values: CLASS_2 CLASS_3 CLASS_9
dg_uncode
required

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
required

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

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
is_lot_code
required

Whether lot-code management is enabled for the goods.

boolean
is_expiration_management
required

Whether shelf-life management is enabled for the goods. When true, shelf_life_attribute_info is required.

boolean
shelf_life_attribute_info

Shelf-life attributes for the goods. The cutoff values must be nonnegative and satisfy sales_cutoff_days < expiration_alert_days < inbound_cutoff_days. If provided, shelf_life must be less than 3650 days.

object
shelf_life

The goods shelf life (days)

integer format: int64
inbound_cutoff_days
required

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
required

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
required

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_expired_goods

How expired inventory is handled. 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_sioc

A flag indicating whether the goods is under 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
bulky_item_attribute

Bulky item info

object
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
Example
{
  "create_goods_dto_list": [
    {
      "tts_sku_id": "723456789012345678",
      "create_goods_type": "CREATE_AND_BIND",
      "goods_name": "Wireless Charging Cable",
      "goods_image_url": "https://example.com/fbt/goods-image.jpg",
      "reference_code": "ABDK999d",
      "barcode_infos": [
        {
          "barcode_type": "UPC",
          "barcode_value": "12345678905"
        }
      ],
      "return_handling_method": "RESTOCK_SELLABLE_DISPOSE_UNSELLABLE",
      "dimension_and_weight_base_info": {
        "weight_value": "500",
        "length_value": "2",
        "width_value": "2",
        "height_value": "3",
        "weight_unit": "GRAM",
        "dimension_unit": "CENTIMETER"
      },
      "is_hazmat": false,
      "hazmat_info": {
        "hazmat_type": "BATTERY",
        "battery_extra_info": {
          "battery_type": "LITHIUM_ION",
          "battery_packaging_type": "STANDALONE",
          "total_battery_weight": "10",
          "total_battery_weight_unit": "GRAM",
          "total_battery_capacity": "2",
          "total_battery_capacity_unit": "WATTHOUR",
          "is_need_un_38_3_test": false,
          "un_38_3_test_file_url": "https://example.com/fbt/un38-3-test-report.pdf",
          "battery_count_per_package": "3"
        },
        "flammable_liquids_extra_info": {
          "flammable_liquids_type": "PAINT",
          "flammable_liquids_volume": "1",
          "volume_unit": "MILLILITERS"
        },
        "dg_class": "CLASS_2",
        "dg_uncode": "UN3480",
        "msds_file_url": "https://example.com/fbt/msds-report.pdf",
        "aerosol_extra_info": {
          "volume": "1",
          "volume_unit": "MILLILITERS"
        }
      },
      "is_lot_code": false,
      "is_expiration_management": false,
      "shelf_life_attribute_info": {
        "shelf_life": 90,
        "inbound_cutoff_days": 100,
        "expiration_alert_days": 90,
        "sales_cutoff_days": 80,
        "handling_method_expired_goods": "DISPOSE"
      },
      "is_sioc": false,
      "sioc_attribute": {
        "sioc_files": [
          {
            "sioc_certification_url": "https://example.com/fbt/sioc-certification.jpg",
            "sioc_file_type": "PHOTO"
          }
        ]
      },
      "bulky_item_attribute": {
        "is_bulky_item_accessories": false
      },
      "goods_safety_attributes": {
        "is_fragile": false,
        "is_liquid": false,
        "is_sharp": false
      }
    }
  ]
}

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
create_result_info

Goods creation result information.

object
create_result_list

List of goods creation results.

Array<object>
object
tts_sku_id

Identifier for the SKU generated by TikTok Shop system.

string
is_success

Whether the goods creation succeeded.

boolean
tts_goods_id

Identifier of the FBT goods record. Returned when is_success is true.

string
fail_reason

Reason the goods record was not created. Returned when is_success is false.

string
Example
{
  "code": 0,
  "data": {
    "create_result_info": {
      "create_result_list": [
        {
          "tts_sku_id": "723456789012345678",
          "is_success": false,
          "tts_goods_id": "9988776655",
          "fail_reason": "Goods creation failed."
        }
      ]
    }
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec