Skip to main content

List Inbound Plans

GET 
/api/tiktok-shop/:integrationInstance/fbt/inbound-plans

Paginated list of Fulfillment by TikTok inbound plans for one integration instance.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

A plan is the seller's intent: the goods, quantities, cartons and the source they ship from. status moves DRAFT → SUBMITTING → PLANNED → CONFIRMED, with CANCELLED and ERROR as terminal outcomes. Once a placement is confirmed the plan is a locked historical record and the shipment belongs to the inbound orders it minted.

Every capability flag ships with a reason: can_submit / can_submit_reason, can_cancel / can_cancel_reason, can_confirm / can_confirm_reason, and is_locked / is_locked_reason. The reason is null exactly when the action is allowed. source_link_status is unresolved, auto or confirmed, and source_blocks_flows is true while no source has been resolved.

Rows in this list carry lines_count and inbound_orders_count; the nested lines, cartons, placement_options and inbound_orders collections are returned by the single-plan read instead.

Filters — every key below is sent as filter[<key>].

Text filters (bare key is an exact match; each also accepts <key>.<operator>): status, source_type, inbound_type, idempotent_key, tiktok_plan_id. Text operators: contains, does_not_contain, is, is_not, is_one_of, is_not_one_of, starts_with, does_not_start_with, ends_with, does_not_end_with, is_empty, is_not_empty.

Numeric filters (bare key plus <key>.<operator>): id, source_warehouse_id, source_supplier_id, created_by_user_id. Numeric operators: is, is_not, is_one_of, is_not_one_of, greater_than, less_than, greater_than_or_equal, less_than_or_equal, between, is_empty, is_not_empty.

Date/time filters (bare key plus <key>.<operator>, values are dates such as 09/15/2026 or 2026-09-15, and between takes two comma-separated values): confirmed_at, created_at. Date operators: is, is_not, before, after, on_or_before, on_or_after, between, is_empty, is_not_empty, today, yesterday, tomorrow, past_week, past_month, past_year, next_week, next_month, next_year, days_ago, days_from_now, past_days, next_days.

Boolean filter: source_confirmed.is (true/false). This one has no bare key — always send the .is form.

Free-text: filter[search] matches the plan reference (idempotent_key), the TikTok plan id, and — through the plan's lines — the seller SKU, TikTok SKU id and FBT goods id. Narrow it with the top-level search_columns parameter (comma-separated, chosen from idempotent_key, tiktok_plan_id, lines.seller_sku, lines.tiktok_sku_id, lines.tiktok_goods_id), and force exact matching on any of those with search_strict_columns.

Advanced filter trees may also be sent as filter_groups — a base64-encoded JSON object of {conjunction, children[]} where each child is {type: "condition", condition: {column, operator, value}}. Columns and operators must be among the ones listed above.

Sorting — sort accepts id, status, inbound_type, source_type, confirmed_at, created_at, updated_at. Prefix with - for descending. Default: -id.

Pagination — page and per_page (default 10).

Requires an authenticated token. No extra permission is needed for this read.

Response addition: total_units, summed in SQL via withSum — the Units column reads it. Null (not 0) when neither the sum nor the lines relation is present, so "unknown" never renders as "no units".

Request​

Responses​

OK

Response Headers
    Content-Type