Skip to content
TikTok Shop Partner API

Update FBT Goods Info

POST
/fbt/202607/goods/update_goods_info

Update FBT goods information, including goods name, image URL, dimensions, hazmat details, shelf-life attributes, and return address information.

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 Body

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

Goods information to update.

Update behavior is field-specific; this object is neither a uniform partial patch nor a full replacement.

Shared fields:

  • tts_goods_id: Identifies the goods record to update; it is not mutable.
  • goods_name, goods_image_url, return_handling_method, and dimension_and_weight_base_info: Replace their stored values.
  • reference_code: If omitted or empty, it is reset to the system-generated fallback.
  • barcode_infos: Replaces the existing barcode set. The FBT system barcode is preserved or added, and existing non-system barcodes omitted from the request are deleted. Removal of a barcode with an inbound record is rejected.
  • is_hazmat: false clears existing hazmat information. true requires valid hazmat_info.

Optional extended fields:

  • is_sioc and sioc_attribute: is_sioc controls Ships in Own Container (SIOC) management. If is_sioc is omitted, no SIOC state or attribute update is requested, and sioc_attribute alone is ignored.
  • goods_safety_attributes: Omitted fragile, liquid, or sharp subfields retain their stored values. A changed value for a locked subfield causes the request to fail; resubmitting the same locked value is a no-op. Supplied editable values are updated.

Do not send explicit null; the public schemas for these fields are non-nullable.

object
tts_goods_id
required

Identifier for goods generated by the Fulfilled by TikTok system.

string
goods_name
required

Name of the goods.

string
goods_image_url
required

Image URL for the goods.

string
reference_code

Reference code for the goods.

string
barcode_infos

Barcode info list

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 stored for the FBT customer return service. This field is required on every update request. Possible values:

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

Dimension and weight info

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
  • GRAM
  • KILOGRAM
  • POUND
  • OUNCE
string
Allowed values: MILLIGRAM GRAM KILOGRAM POUND OUNCE
dimension_unit
required

Dimension unit. Possible values:

  • MILLIMETER
  • CENTIMETER
  • METER
  • FOOT
  • INCH
string
Allowed values: MILLIMETER CENTIMETER METER FOOT INCH
is_hazmat
required

Whether is hazmat goods

boolean
hazmat_info

Hazmat information used when is_hazmat is true.

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

If the product requires lot management based on FBT category rule TRUE:this product requires lot control FALSE:this product does not require lot control

boolean
is_expiration_management
required

Whether the goods require expiration management.

boolean
shelf_life_attribute_info

Shelf-life attributes for the goods.

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

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
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
{
  "update_goods_dto": {
    "tts_goods_id": "8839232030",
    "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": "223333"
      }
    ],
    "return_handling_method": "RESTOCK_SELLABLE_DISPOSE_UNSELLABLE",
    "dimension_and_weight_base_info": {
      "weight_value": "500",
      "length_value": "40",
      "width_value": "20",
      "height_value": "30",
      "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_3",
      "dg_uncode": "UN2807",
      "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": 10,
      "inbound_cutoff_days": 90,
      "expiration_alert_days": 80,
      "sales_cutoff_days": 70,
      "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
update_result_info

Goods update result information.

object
tts_goods_id

Identifier for goods generated by Fulfilled by TikTok system

string
is_success

Whether the goods update succeeded.

boolean
fail_reason

Reason the goods update failed.

string
Example
{
  "code": 0,
  "data": {
    "update_result_info": {
      "tts_goods_id": "1233444",
      "is_success": true,
      "fail_reason": "Goods update failed."
    }
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec