来自 TikTok Shop 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Overview
Effective date: July 24, 2026.
On July 24, 2026, TikTok Shop introduced two fulfillment APIs in API version v202607 for apps that handle customs information in the Japan order fulfillment flow. The APIs let your app determine whether an order requires customs information and submit item-level composition data before package fulfillment.
This change applies to ERP, warehouse management system (WMS), and fulfillment apps that process applicable TikTok Shop orders. The two new endpoints add a conditional customs-information step without changing existing order or package API schemas.
§2 What is changing
Your app will add a customs-information check between order retrieval and package fulfillment. If TikTok Shop indicates that an order requires customs information, your app must collect and submit the required item data before continuing the package flow.
| Stage | Previous flow | Updated flow |
|---|---|---|
| After order retrieval | Your app proceeds to package fulfillment. | Your app queries whether each order requires customs information. |
| When customs information is required | No API step is defined in the existing flow. | Your app collects item composition data and submits it to TikTok Shop. |
| Before package fulfillment | Your app creates or ships the package through the existing fulfillment flow. | Your app continues only after the customs information submission succeeds. |
§3 Affected APIs
Affected APIs
| API | Method and path | Purpose |
|---|---|---|
| Get Order Customs Requirements | POST /fulfillment/202607/orders/customs_info/query | Check whether orders require customs information and retrieve the item structure needed for submission. |
| Upload Customs Information | POST /fulfillment/202607/orders/customs_info/submit | Submit customs information for the applicable orders and order line items. |
§4 Query customs requirements
Query customs requirements
Call the Get Order Customs Requirements API with the TikTok Shop order IDs in order_ids.
| Field | Type | How to use it |
|---|---|---|
order_ids | Array of strings | Send the TikTok Shop order IDs that your app needs to evaluate. |
data.order_clearance_list[].order_id | String | Map each result to the corresponding TikTok Shop order. |
data.order_clearance_list[].need_fill_clearance | Boolean | If true, collect and submit customs information before continuing fulfillment. If false, continue the existing package flow. |
data.order_clearance_list[].already_filled_clearance | Boolean | Indicates whether customs information has already been submitted for the order. |
data.order_clearance_list[].target_country | String | Identifies the target market. This flow returns JP for orders in the Japan market. |
data.order_clearance_list[].biz_type | Integer | Identifies the seller business type: 1 for FS seller and 2 for POP seller. |
data.order_clearance_list[].shipment_type | Integer | Identifies the shipping type: 1 for international shipping and 2 for local shipping. |
data.order_clearance_list[].item_list[] | Array of objects | Use the returned order line, product, SKU, and item relationship data to prepare the customs submission. |
§5 Submit customs information
Submit customs information
Call the Upload Customs Information API for each order that requires customs information. Map the order, order line, SKU, quantity, and percentage fields from your app to the request structure.
| Field | Type | Description |
|---|---|---|
order_list[] | Array of objects | Contains the customs information to submit for one or more orders. |
order_list[].order_id | String | The TikTok Shop order ID. |
order_list[].item_list[] | Array of objects | Contains the customs information associated with each order line. |
order_list[].item_list[].order_line_id | String | The TikTok Shop order line ID. |
order_list[].item_list[].sku_id | String | The TikTok Shop SKU ID associated with the order line. |
order_list[].item_list[].item_detail[] | Array of objects | Contains the SKU composition data associated with the order line. |
order_list[].item_list[].item_detail[].sku_id | String | The SKU ID for the related item. |
order_list[].item_list[].item_detail[].qty | Integer | The SKU quantity. |
order_list[].item_list[].item_detail[].price_percent | Integer | The percentage of the order line price attributed to the related item. For example, 10 represents 10%. |
§6 How to integrate
#§7 Use the new API version
Use the new API version
Add the two v202607 endpoints to your fulfillment integration. You do not need to migrate your existing order or package endpoints.
§8 Update your fulfillment flow
Update your fulfillment flow
- Retrieve orders. Continue using your existing order retrieval integration.
- Query customs requirements. Send the relevant order IDs in
order_idstoPOST /fulfillment/202607/orders/customs_info/query. - Evaluate each order. Use
need_fill_clearanceandalready_filled_clearanceto choose the next action. - Map item data. Associate each order line with its SKU composition, quantity, and price percentage.
- Submit customs information. Send
order_listtoPOST /fulfillment/202607/orders/customs_info/submit. - Continue fulfillment. Create or ship the package only after the required customs submission succeeds.
§9 Handle each order state
Handle each order state
| Condition | Meaning | Required app action |
|---|---|---|
need_fill_clearance = false | The order does not require customs information through this flow. | Continue the existing package fulfillment flow. |
need_fill_clearance = true and already_filled_clearance = false | The order requires a customs submission. | Collect, validate, and submit the item data before package fulfillment. |
already_filled_clearance = true | TikTok Shop already has customs information for the order. | Continue the applicable fulfillment flow. |
§10 Validate item composition
Validate item composition
- Map each
order_line_idto the correctsku_id. - Send a positive integer in
qtyfor each related item. - Send
price_percentas an integer percentage. For example, send10for 10%. - Review the item composition payload for completeness before submission.
§11 Handle API errors
Handle API errors
| Error code | Error message | Recommended app action |
|---|---|---|
11001002 | Request parameter is invalid. | Correct the request. Do not retry the same payload without changes. |
11001012 | Downstream service timed out. | Retry with exponential backoff and preserve idempotency. |
11001027 | Lock acquisition failed. | Retry with exponential backoff. |
11001001 | Database error. | Retry with backoff. Escalate persistent failures with the request_id. |
§12 Timeline and enforcement
| Date | What happens |
|---|---|
| July 24, 2026 | The two v202607 customs information APIs became available to apps. |
§13 FAQ
Q: Does every order require a customs information submission?
A: No. Query the order first. Submit customs information only when need_fill_clearance is true and already_filled_clearance is false.
Q: What should my app do when customs information is already present?
A: If already_filled_clearance is true, TikTok Shop already has customs information for the order. Continue the applicable fulfillment flow.
Q: Does this change existing order or package API schemas?
A: The two new fulfillment endpoints do not change existing order or package API schemas. However, affected apps must add a conditional step before package fulfillment.
Q: Which sellers and orders are affected?
A: This change applies to orders in the Japan customs flow. Use target_country to identify the target market and apply the new flow only to applicable orders.