Status Change Endpoint

Updated today

Set the status on the movement named in native_system_load_leg_id to the code in native_system_load_leg_status. We send a status change when a tracker changes the load's status in TrackFlo, and when a stop event moves the load to a new status, such as an arrival at the pickup.

Suggested path: POST /trackflo/status-changes. Authentication, the shared fields, responses and retries are in Build Write-Back Endpoints for TrackFlo.

Fields

Every request carries the shared fields plus these. event_type is status_change.

Field	Type	Description
`native_system_load_leg_status`	string	The new status, as one of your TMS's own status codes.
`status_date_time_utc`	string	When the status took effect.
`status_date_time_local`	string or null	The same time, local to the stop or location the status is about.
`status_iana_timezone`	string or null	The timezone of `status_date_time_local`.
`trigger`	string	`manual` when a tracker set the status, `stop_event` when a stop event moved it.
`native_system_stop_id`	string or null	The stop the status is about, when there is one (for example, the pickup for an at-pickup status).
`comment`	string or null	The tracker's comment, up to 600 characters.

Example

{
  "event_id": "c7d4b1a9-52e0-4c33-8f17-6a2e90d5b4f8",
  "event_type": "status_change",
  "native_system_load_id": "1089520",
  "native_system_load_leg_id": "2330158",
  "entered_by_name": "Jordan Ellis",
  "entered_by_email": "[email protected]",
  "entered_by_tms_user_id": "JELLIS",
  "entered_at_utc": "2026-10-25T13:05:45Z",
  "trackflo_load_url": "https://app.trackflo.tech/public_load_details/4b6e…",
  "native_system_load_leg_status": "ATDEL",
  "status_date_time_utc": "2026-10-25T12:10:00Z",
  "status_date_time_local": "2026-10-25T07:10:00",
  "status_iana_timezone": "America/Chicago",
  "trigger": "stop_event",
  "native_system_stop_id": "88214",
  "comment": null
}

Respond with { "id": "<your record id>" }, or { "id": null } if your TMS keeps no record of status changes.

Your status codes

We only ever send codes from your own list. During onboarding we agree two things with you:

Which statuses a tracker can set from TrackFlo. Most teams pick a short set such as dispatched, at pickup, in transit, at delivery and delivered.
Which status each stop event implies. For example, an arrival at the first pickup becomes your at-pickup code, and a departure from the final delivery becomes your delivered code.

Answer an unknown code with 422 and a message that names it. The tracker sees the message, and we fix the mapping.

Things to know

Order by status_date_time_utc. A retried status change can arrive after a newer one. Skip a status change whose time is older than the status you already hold for that leg.
Apply it to the leg, not the order. On a split order each leg moves through its own statuses: the first carrier can be delivered at the cross-dock while the second is still at pickup.

Was this helpful?