container.itinerary.updated

Overview

Fired when the itinerary details of a container voyage change. This includes updates to the vessel, voyage number, ETA, ETD, port of loading, port of discharge, destination terminal, rail station, and other routing details.

When This Event Fires

The system detects a difference in itinerary-related fields between the previous and current container snapshot. Common triggers include:

ETA at the destination terminal changes
ETD from origin changes
Vessel or voyage number changes (but not due to a cargo roll — that fires container.exceptions.updated with rolledCargo)
Port of discharge or destination port changes
Terminal at the destination port changes
Rail carrier or final rail station assignment changes
Off-dock facility assignment changes

Payload Structure

{
  "event": "container.itinerary.updated",
  "data": { /* IContainerVoyageResponse — full container snapshot */ },
  "changes": {
    "etaAtTerminal": {
      "previous": "2025-07-15T00:00:00.000Z",
      "current": "2025-07-18T00:00:00.000Z"
    },
    "vessel": {
      "previous": { "name": "EVER GIVEN", "imo": "9811000" },
      "current": { "name": "EVER ACE", "imo": "9893890" }
    }
  },
  "deliveryAttempt": 1,
  "pendingRetries": 4,
  "sentAt": "2025-07-19T17:00:00.654Z"
}

`data` object

The full current state of the container, identical to the GET /v1/container/:containerId response.

`changes` object

Contains { previous, current } pairs for each itinerary field that changed. Possible fields include:

Field	Description
`etaAtTerminal`	ETA at destination terminal
`etdFromOrigin`	ETD from origin port
`vessel`	Current vessel (mapped to public format)
`terminalAtDestinationPort`	Terminal at destination port
`terminalAtOriginPort`	Terminal at origin port
`originPort`	Origin port location
`destinationPort`	Destination port location
`railCarrier`	Rail carrier
`finalDestination`	Final inland destination
`currentLocation`	Current location

Common Use Cases

Use Case	How to Implement
ETA change alerts	Check if `changes.etaAtTerminal` is present and notify stakeholders when the ETA shifts significantly
Vessel swap detection	Check if `changes.vessel` is present to detect when a container is reassigned to a different vessel
Terminal reassignment	Monitor `changes.terminalAtDestinationPort` to detect when a container is rerouted to a different terminal
Appointment scheduling	Use ETA updates to proactively schedule or reschedule pickup appointments at the terminal
Drayage planning	React to ETA and terminal changes to adjust drayage dispatch and trucker scheduling
TMS/ERP sync	Push updated ETAs, terminals, and routing info to downstream systems on every itinerary change

Updated about 4 hours ago