shipment.itinerary.updated

Overview

In this doc, a shipment is the carrier booking you are tracking, identified by a master bill of lading number or a booking reference number (whichever the carrier has issued at this stage).

Fired when routing or schedule details change on a shipment that is still at the booking stage (before the carrier assigns container numbers). The payload reflects the booked shipment as a whole, with one entry in containers per booked container slot.

When This Event Fires

This event will only fire while the shipment is still in BOOKED status (before the carrier assigns containers to it). This includes changes to:

ETA, ETD, or other schedule dates at the shipment level
Vessel or voyage information
Port assignments
Terminal assignments

This event does not fire once containers are assigned, or for canceled bookings. After container assignment, itinerary updates are delivered per container via container.itinerary.updated.

📘
When to use which event

Use shipment.itinerary.updated while tracking a shipment at the booking stage (before container numbers are assigned). You get one shipment-level payload; containers lists each booked container slot (size and type), not yet real container IDs.

Use container.itinerary.updated after containers are assigned for ongoing per-container itinerary updates through the rest of the journey.

Payload Structure

{
  "event": "shipment.itinerary.updated",
  "data": {
    "masterBillNumber": "MEDU1234567",
    "scacCode": "MSCU",
    "status": "BOOKED",
    "account": {
      "region": "US",
      "domain": "example.com"
    },
    "customFields": [
      { "name": "poNumber", "value": "PO-12345" }
    ],
    "containers": [
      { /* container status response for container 1 */ },
      { /* container status response for container 2 */ }
    ]
  },
  "changes": {
    "loadingVessel": {
      "previous": null,
      "current": { "name": "VESSEL NAME", "imo": "...", "mmsi": "..." }
    },
    "terminalAtOriginPort": {
      "previous": null,
      "current": { "name": "Terminal Name", "firmsCode": "..." }
    }
  },
  "deliveryAttempt": 1,
  "pendingRetries": 4,
  "sentAt": "2025-07-19T17:00:00.654Z"
}

`data` object fields

The top-level data object uses the same shape as the container status response (GET /v1/containers/{containerId}), plus a containers array with one entry per booked container slot.

Field	Description
`masterBillNumber`	Shipment identifier. The master bill of lading number when the carrier has issued one; otherwise the booking reference number
`scacCode`	Carrier SCAC code
`status`	Shipment status (for example `BOOKED` before container numbers are assigned)
`account`	Account `domain` and `region`
`customFields`	Account-configured custom fields (for example PO numbers) as `{ name, value }` objects
`containers`	One container status response per booked container slot (size, type, and shared routing)

📘
At the booking stage you may only have a booking reference, not a master bill of lading number yet. OpenTrack still returns it in the field masterBillNumber.

Each entry in containers uses the same format as GET /v1/containers/{containerId}. Before container numbers are assigned, containers has one entry per booked container slot (showing size, type, and shared routing), not individual tracked containers yet.

`changes` object

changes is a sibling of data at the root of the webhook payload (not nested inside data). It contains { previous, current } pairs for each itinerary field that changed, such as loadingVessel, loadingVoyageNumber, terminalAtOriginPort, originPort, and destinationPort.

Common Use Cases

Use Case	How to Implement
Pre-assignment Receiving Window changes	Notify operators when Receiving Windows change (Cutoff & Early Return Dates at port and rail) so they can better plan when to pull the empty containers and avoid unnecessary storage fees from surprise changes.
Booking-level itinerary sync	Subscribe while tracking shipments at the booking stage; push `changes` (vessel, ports, terminals, schedule dates) to your TMS before container numbers exist
Pre-assignment ETA alerts	Notify planners when the carrier updates schedule on a booked shipment before container assignment
Booked equipment visibility	Use the `containers` array to show how many containers were booked, their sizes and types, and shared routing on a booking dashboard

Overview

When This Event Fires

When to use which event

Payload Structure

data object fields

At the booking stage you may only have a booking reference, not a master bill of lading number yet. OpenTrack still returns it in the field masterBillNumber.

changes object

Common Use Cases

`data` object fields

At the booking stage you may only have a booking reference, not a master bill of lading number yet. OpenTrack still returns it in the field `masterBillNumber`.

`changes` object