Creates a new inbound plan or fully replaces the contents of an existing inbound plan by using a goods item list or carton configurations with dimensions. Omit plan_id to create a plan; provide it to update one. Provide exactly one non-empty array: goods_items or cartons; do not provide both.
For an update, submit the complete desired goods or carton contents; previously stored goods or cartons omitted from the request are not retained. Using goods_items clears existing carton and lot/expiration data. Using cartons rebuilds the carton and item data.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Identifies the shop. Obtain it from the Get Authorized Shops API.
Request Body
Section titled “Request Body”object
Without plan id it is creating, with plan id it is updating.
Idempotency key for creating an inbound plan. Required when plan_id is not provided.
Goods item list.
object
The Fulfilled by TikTok goods identifier for this inbound plan item. The goods must belong to the merchant associated with the authenticated seller, be approved for fulfillment, and be matched to an SKU.
Quantity of this goods item in the inbound plan. Must be greater than 0.
Carton List.
object
Indicates whether the carton is configured as single-SKU or multi-SKU.
Possible values:
SINGLE_SKU:itemsmust contain exactly one item.MULTI_SKU:itemsmust contain two or more items.
Goods item list of a carton.
object
The Fulfilled by TikTok goods identifier for this carton item. The goods must belong to the merchant associated with the authenticated seller, be approved for fulfillment, and be matched to an SKU.
Quantity of this goods item in each carton. Must be greater than 0.
Lot code for this goods item. Required when lot-code management is enabled for the goods. Every occurrence of the same goods_id in cartons must use the same lot_code and expiration_timestamp values.
The expiration date for this item, as a Unix timestamp in seconds. Required when expiration management is enabled for the goods. It must be no earlier than the current time plus the goods-specific inbound_cutoff_days. Obtain this value from data.goods[].lot_expiration_info.inbound_cutoff_days in Search Goods Info (POST /fbt/202607/goods/search).
Number of cartons that use this carton configuration.
Identifiers assigned to the cartons represented by this configuration. Either every carton configuration in the request must provide a non-empty carton_nums array, or no configuration may provide any carton identifiers. When provided, the number of identifiers must equal this configuration’s quantity; each identifier must use the format C followed by four digits and must be unique across the request. If none are provided, carton identifiers are generated automatically.
Carton measurement.
object
Carton weight.
The unit used for the carton’s weight value.
Possible values:
KILOGRAM(kg)GRAM(g)MILLIGRAM(mg)POUNDS(lbs)OUNCE(oz)
Carton width.
Carton height.
Carton length.
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)
Example
{ "plan_id": "5766071177167344427", "idempotent_key": "9ef6857095f84893", "goods_items": [ { "goods_id": "231313", "quantity": 400 } ], "cartons": [ { "carton_type": "SINGLE_SKU", "items": [ { "goods_id": "12345", "quantity": 20, "lot_code": "sfsfnjkfvv", "expiration_timestamp": "1623812664" } ], "quantity": 2, "carton_nums": [ "C0001", "C0002" ], "box_measurements": { "weight": "3.50", "weight_unit": "POUNDS", "width": "1.2", "height": "2", "length": "5", "length_unit": "INCH" } } ]}Responses
Section titled “Responses”Success
object
Status code; 0 means success.
Success or failure message.
Request log ID.
object
Inbound plan.
object
Plan identifier.
Example
{ "code": 0, "data": { "inbound_plan": { "plan_id": "5766071177167344427" } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7"}