Skip to main content

Create Inbound Plan Draft

POST 
/api/tiktok-shop/:integrationInstance/fbt/inbound-plans/drafts

Open a local inbound plan draft. Nothing exists at TikTok yet and no stock is reserved, so a draft is the one state in which a plan can be hard-deleted.

Not yet available to API tokens

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

Validation here is deliberately permissive — a draft is a scratchpad, so the delivery mode, the cartons and even the lines are all optional. The full shipment contract is enforced when the plan is submitted.

Body

  • source_type (string, optional) — 3pl, supplier or direct.
  • source_warehouse_id (integer, optional, nullable) — must be an existing warehouse.
  • source_supplier_id (integer, optional, nullable) — must be an existing supplier.
  • source_confirmed (boolean, optional).
  • inbound_type (string, optional, nullable) — CARTON_SPLITTING or UNIT_SPLITTING.
  • lines (array, optional, max 500) — replaces the plan's lines wholesale when present.
    • lines.*.product_id (integer, optional, nullable) — the SKU.io product. Must exist.
    • lines.*.tiktok_sku_id (string, required when lines is present, max 64) — the shop SKU the units inbound as.
    • lines.*.tiktok_goods_id (string, optional, nullable, max 64) — the FBT goods record. Resolved from the SKU's binding when omitted.
    • lines.*.seller_sku (string, optional, nullable, max 255).
    • lines.*.quantity (integer, required when lines is present, min 1) — TikTok's 10-unit per-SKU minimum is checked at submit, not here.
    • lines.*.prep_instructions (string, optional, nullable, max 2000).
    • lines.*.prep_owner (string, optional, nullable, max 16) — defaults to fulfiller.
    • lines.*.kit_source (string, optional, nullable) — built (default) or components.
  • cartons (array, optional, max 500).
    • cartons.*.carton_number (integer, optional, min 1) — defaults to the carton's position.
    • cartons.*.carton_type (string, optional) — SINGLE_SKU (default) or MIXED_SKU.
    • cartons.*.weight_kg (numeric, optional, nullable, min 0).
    • cartons.*.length_cm (numeric, optional, nullable, min 0).
    • cartons.*.width_cm (numeric, optional, nullable, min 0).
    • cartons.*.height_cm (numeric, optional, nullable, min 0).
    • cartons.*.contents (array, optional).
      • cartons.*.contents.*.line_index (integer, optional, min 0) — addresses a line by its position in the lines array of this same request, because on the first save the lines have no ids yet.
      • cartons.*.contents.*.plan_line_id (integer, optional, nullable) — an existing line id, used instead of line_index when one is known.
      • cartons.*.contents.*.quantity (integer, required when contents are present, min 1).
      • cartons.*.contents.*.lot_code (string, optional, nullable, max 64) — required by TikTok for lot-managed goods.
      • cartons.*.contents.*.expiration_at (date, optional, nullable) — required by TikTok for expiration-managed goods.

Returns 201 with the created plan, including its lines, cartons, placement options and inbound orders.

Requires the integrations.update permission.

Source warehouse restriction: source_warehouse_id must be a warehouse SKU.io keeps its own movement ledger for — the source is what shipping decrements. Marketplace-held warehouses (Amazon FBA/AWD, Walmart WFS, TikTok FBT, and virtual), legacy rows carrying subtype = amazon_fba, and dropship/supplier warehouses are rejected with a 422. Faire FBF is accepted: Faire exposes no inventory API, so SKU.io's ledger is the system of record for FBF stock.

Request​

Responses​

Created

Response Headers
    Content-Type