Print Inbound Order Labels

POST

/fbt/202602/inbound_orders/label_print

This API generates label files for an inbound order using an asynchronous Long-Running Operation (LRO). The inbound order must be shipped or in a later eligible status and must not be canceled.

Format applicability

• carton_label_format controls the carton or pallet label layout only when print_items includes CARTON_PALLET_LABEL.
• barcode_format controls the goods-barcode label layout only when print_items includes FBT_BARCODE.

The selected print_items and both resolved format values are part of the print task identifier, so keep the same selections in every polling request.

Workflow

1. Initiate. Send a request with the child inbound order_id and the desired print_items. The API returns PROCESSING while the label file is being generated; a completed task for the same request values may return SUCCESS immediately.
2. Poll. If task_status is PROCESSING, repeat the request with the same order_id, print_items, carton_label_format, and barcode_format values. Poll every 3–5 seconds.
3. Complete. When task_status is SUCCESS, download_url contains the generated ZIP file.

Authorizations

• accessToken

Parameters

Query Parameters

shop_cipher

required

string

Identifies the shop. Obtain it from the Get Authorized Shops API.

Request Body^required

Media typeapplication/json

object

order_id

required

The numeric identifier of the child inbound order to print labels for.

Note: Provide the numeric sequence only; do not include the IBR prefix (for example, use 123456 instead of IBR123456). Do not use an inbound plan ID.

string

print_items

Specifies the types of documents to generate. Multiple values can be included in one combined output.

Allowed Values:

• CARTON_PALLET_LABEL: Identification labels for cartons or pallets. Apply carton labels to at least two adjacent sides of each carton.
• PACKING_PICKING_LIST: Warehouse document for identifying and packing items.
• FBT_BARCODE: Fulfilled by TikTok barcode labels.

Note: If this list is empty or omitted, CARTON_PALLET_LABEL is generated by default.

Array<string>

Allowed values: CARTON_PALLET_LABEL PACKING_PICKING_LIST FBT_BARCODE

carton_label_format

Specifies the layout and dimensions for the carton labels. If this parameter is omitted or an invalid value is provided, the system will use the default single-label format.

Allowed Values:

• DEFAULT_1UP: Standard format (1 label per page).
• A4_4UP: A4 paper format (4 labels per page).

Note: If no value is provided, DEFAULT_1UP will be used as the default format.

string

Allowed values: DEFAULT_1UP A4_4UP

barcode_format

Specifies the layout and dimensions for the generated label PDF. If this parameter is omitted or an invalid value is provided, the system will use the default thermal label format.

Allowed Values:

Standard / Default

• DEFAULT_40MM_60MM: Standard 40mm x 60mm thermal label format

A4 Paper Layouts

• A4_21UP_60_0MM_40_0MM: 21-up labels (60.0mm x 40.0mm) on A4
• A4_21UP_63_5MM_38_1MM: 21-up labels (63.5mm x 38.1mm) on A4
• A4_24UP_63_5MM_33_9MM: 24-up labels (63.5mm x 33.9mm) on A4
• A4_24UP_64_6MM_33_8MM: 24-up labels (64.6mm x 33.8mm) on A4
• A4_24UP_66_0MM_33_9MM: 24-up labels (66.0mm x 33.9mm) on A4
• A4_24UP_66_0MM_35_0MM: 24-up labels (66.0mm x 35.0mm) on A4
• A4_24UP_70_0MM_36_0MM: 24-up labels (70.0mm x 36.0mm) on A4
• A4_24UP_70_0MM_37_0MM: 24-up labels (70.0mm x 37.0mm) on A4
• A4_27UP_63_5MM_29_6MM: 27-up labels (63.5mm x 29.6mm) on A4
• A4_40UP_52_5MM_29_7MM: 40-up labels (52.5mm x 29.7mm) on A4
• A4_44UP_48_5MM_25_4MM: 44-up labels (48.5mm x 25.4mm) on A4

US Letter Layouts

• US_LETTER_30UP_1IN_2_625IN: 30-up labels (1” x 2-5/8”) on US Letter

Note: If no value is provided, DEFAULT_40MM_60MM will be used as the default format.

string

Example

{
  "order_id": "5766071177167344427",
  "print_items": [
    "CARTON_PALLET_LABEL",
    "FBT_BARCODE",
    "PACKING_PICKING_LIST"
  ],
  "carton_label_format": "DEFAULT_1UP",
  "barcode_format": "DEFAULT_40MM_60MM"
}

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

download_url

URL containing labels for the inbound order.

Please note: the URL will be unicode-escaped. If attempting to manually paste the URL into a browser, you will need to unescape the URL first (e.g. ‘\u0026’->‘&’)

string

task_status

• PROCESSING: Task is currently being processed. Continue to periodically poll.
• SUCCESS: Task is finished. download_url should be included in response

string

Example

{
  "code": 0,
  "data": {
    "download_url": "https://example.com/fbt/inbound_files.zip?download_token=sample_token",
    "task_status": "PROCESSING"
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}