Skip to main content

Submit Bulk Fulfillments

POST 
/api/tiktok-shop/integration-instances/:integration_instance_id/fulfillments/submit-bulk

Reports the shipment of the listed fulfillments to TikTok Shop.

Not yet available to API tokens

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

Authentication: Requires Bearer token. Requires the sales_orders.fulfill permission.

Body:

  • ids (array of integers, required): sales order fulfillment ids. Each must exist. Ids that are not pending on this integration are skipped and reported in skipped_details.
  • force_submit (boolean, optional, default false): submit even when SKU.io is not running in production. It does not bypass the integration's sync controls.

For each fulfillment, SKU.io marks the TikTok package shipped with the fulfillment's tracking number and its carrier, matched to one of TikTok Shop's shipping providers for the order's delivery option. The fulfillment is then marked as submitted. Outcomes:

  • Submitted: TikTok Shop accepted the shipment.
  • Already shipped: TikTok Shop already had every item shipped; nothing new is sent and the fulfillment is marked as submitted.
  • Skipped: nothing is sent, and the fulfillment is left as it is. This happens when the fulfillment is not pending on this integration (already submitted, not fulfilled, a pickup, a cancelled sales order, or another integration's order), TikTok ships the order itself, or the TikTok order is cancelled.
  • Failed: for example, a missing tracking number, a carrier that matches none of TikTok Shop's shipping providers, or TikTok Shop rejecting the shipment. The reason is returned and also recorded on the fulfillment and the sales order.

Response (200) when anything was submitted or failed: success is true when nothing failed; data.submitted counts fulfillments submitted or already shipped, data.failed counts failures and data.skipped counts fulfillments nothing was sent for. errors lists each failure as {id, message}; skipped_details lists each skipped fulfillment as {id, reason, message}.

Nothing sent returns 409, never a success. The body is {success: false, skipped: true, reason, message}, and message says why and what to do:

  • reason: sync_disabled (also skipped_sync_disabled: true): outbound Tracking sync is turned off for this integration. Turn it on in the TikTok Shop integration's sync controls. force_submit does not bypass this. A paused sync schedule does not block these endpoints: pausing stops only the automatic submissions.
  • reason: non_production (also skipped_non_production: true): SKU.io is not running in production and force_submit was not true. Send again with force_submit: true to submit anyway.
  • reason: nothing_eligible: none of the listed fulfillments could be submitted. data and skipped_details say why for each.

Request​

Responses​

OK

Response Headers
    Content-Type