Skip to main content

Update Inbound Plan Cartons

PATCH 
/api/tiktok-shop/:integrationInstance/fbt/inbound-plans/:plan/cartons

Replace the plan's entire carton set. Send every carton — what you send becomes what is on file.

Not yet available to API tokens

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

Body

  • cartons (array, required, max 500).
    • cartons.*.carton_number (integer, required, min 1).
    • 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, required, min 1 entry).
      • cartons.*.contents.*.plan_line_id (integer, required) — must be a line on this plan.
      • cartons.*.contents.*.quantity (integer, required, 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.

Two further rules are enforced against the plan itself and reported as 422:

  • Conservation — the carton contents for each line must sum exactly to that line's quantity. Errors come back on lines.{index}.cartons.
  • Single-SKU cartons — a carton typed SINGLE_SKU may hold only one line. Errors come back on cartons.{index}.carton_type.

Cartons can no longer be changed once any inbound order under the plan has physically departed; that answers 409. The plan must belong to the integration instance in the path; a plan owned by another instance answers 404.

Requires the integrations.update permission.

Request​

Responses​

OK

Response Headers
    Content-Type