Skip to main content

Register Parcel Trackings (Multi-Parcel)

POST 
/api/shipment-trackings/register-parcels

Register additional parcel tracking numbers against ONE entity — the multi-parcel path for shipments split across several cartons (each with its own carrier number). The entity's primary tracking_number is registered by the save observer; this endpoint covers the remaining boxes so every carton tracks independently.

Authorization

Any valid API token can call this endpoint — no specific scope required. Manage tokens.

Request body:

  • trackable_type (string, required) — one of sales_order_fulfillment, inbound_shipment, warehouse_transfer_shipment, rma, vendor_credit_shipment
  • trackable_id (integer, required) — ID of the entity
  • tracking_numbers (string[], required, 1–40 items) — parcel tracking numbers to register

Numbers already tracked for the entity are skipped; garbage values (n/a, local pickup, …) are dropped; new rows are created pending and pushed via the debounced batch register job. Respects the per-entity auto-track toggle.

Responses:

  • 201 Created — array of the queued tracking rows
  • 422 Unprocessable Entity with code: register_skipped — every number was already tracked / dropped, or auto-track is disabled for this entity type
  • 422 Unprocessable Entity with code: not_connected — 17TRACK is not connected
  • 404 Not Found — trackable entity does not exist

This manual action bypasses the auto_track_channels sales-channel scoping — an explicit request to track one shipment always registers it, even if its channel is excluded from automatic tracking.

Request​

Responses​

Created

Response Headers
    Content-Type