Guides
Guides
Start typing to search…

container.exceptions.updated

Overview

Fired when an exception (anomaly) is detected on a container. Exceptions are intelligent alerts that identify supply chain disruptions such as cargo rolls, demurrage risk, rail dwelling, active holds, split cargo, street dwelling, and ISF-5 filing requirements.

When This Event Fires

The system identifies a new exception condition on a container. Each exception has a distinct exceptionName that determines the payload shape:

Exception NameWhen It Fires
rolledCargoThe container was rolled to a different vessel, detected via vessel and/or ETA changes
demurrageRiskThe container is at risk of incurring demurrage charges (approaching or past LFD)
demurrageDetectedDemurrage charges have been detected on the container
activeHoldAn active hold is preventing container release
railDwellThe container has been dwelling at a rail facility longer than expected
streetDwellThe container has been on the street (outgated but not returned empty) longer than expected
noRailSightingsA rail-bound container has not had any rail sightings within the expected window
splitCargoContainers on the same booking are on different vessels or have diverging timelines
isf5RequirementDetectedAn ISF-5 filing is required because the port of discharge is in the US but the final destination is outside the US

Payload Structure

The payload shape varies by exception type. All exception payloads share a common base:

{
  "event": "container.exceptions.updated",
  "data": {
    "containerId": "MSCU1234567",
    "masterBillNumber": "MEDU1234567",
    "scacCode": "MSCU",
    "exceptionName": "rolledCargo",
    "context": { /* exception-specific fields */ }
  },
  "deliveryAttempt": 1,
  "pendingRetries": 4,
  "sentAt": "2025-07-19T17:00:00.654Z"
}
⚠️

Unlike most other container events, the data object for exceptions is not the full container snapshot. It is a focused payload with the exception-specific context.

Exception-specific context fields

rolledCargo
{
  "context": {
    "originPort": { "name": "Shanghai", "unlocode": "CNSHA" },
    "destinationPort": { "name": "Los Angeles", "unlocode": "USLAX" },
    "previousVessel": { "name": "EVER GIVEN", "imo": "9811000" },
    "currentVessel": { "name": "EVER ACE", "imo": "9893890" },
    "previousEta": "2025-07-15T00:00:00.000Z",
    "currentEta": "2025-07-22T00:00:00.000Z"
  }
}
demurrageRisk
{
  "context": {
    "status": "DISCHARGED",
    "lastFreeDay": "2025-07-20T00:00:00.000Z",
    "lineLastFreeDay": "2025-07-18T00:00:00.000Z",
    "lastFreeDayAtRailStation": null,
    "isRailMove": false,
    "originPort": { "name": "Shanghai", "unlocode": "CNSHA" },
    "destinationPort": { "name": "Los Angeles", "unlocode": "USLAX" }
  }
}
demurrageDetected
{
  "context": {
    "status": "AVAILABLE",
    "demurrageOwedAtPort": 275.50,
    "demurrageOwedAtRailStation": null,
    "isRailMove": false,
    "originPort": { "name": "Shanghai", "unlocode": "CNSHA" },
    "destinationPort": { "name": "Los Angeles", "unlocode": "USLAX" }
  }
}
activeHold
{
  "context": {
    "status": "DISCHARGED",
    "holds": [
      { "type": "CUSTOMS", "code": "1H", "reportedAt": "2025-07-10" }
    ],
    "originPort": { "name": "Shanghai", "unlocode": "CNSHA" },
    "destinationPort": { "name": "Los Angeles", "unlocode": "USLAX" }
  }
}
railDwell
{
  "context": {
    "status": "ARRIVED_AT_RAIL_FACILITY",
    "originPort": { "name": "Shanghai", "unlocode": "CNSHA" },
    "destinationPort": { "name": "Chicago", "unlocode": "USCHI" },
    "dischargedDate": "2025-07-05T00:00:00.000Z"
  }
}
streetDwell
{
  "context": {
    "status": "FULL_OUTGATED",
    "originPort": { "name": "Shanghai", "unlocode": "CNSHA" },
    "destinationPort": { "name": "Los Angeles", "unlocode": "USLAX" },
    "outgatedDate": "2025-07-10T00:00:00.000Z",
    "emptyReturnedDate": null,
    "detentionLastFreeDay": "2025-07-20T00:00:00.000Z"
  }
}
noRailSightings
{
  "context": {
    "status": "LOADED_ON_RAIL",
    "lastKnownPositionDate": "2025-07-08T00:00:00.000Z",
    "originPort": { "name": "Los Angeles", "unlocode": "USLAX" },
    "destinationPort": { "name": "Chicago", "unlocode": "USCHI" }
  }
}
splitCargo
{
  "context": {
    "status": "LOADED",
    "originPort": { "name": "Shanghai", "unlocode": "CNSHA" },
    "destinationPort": { "name": "Los Angeles", "unlocode": "USLAX" },
    "siblingContainers": ["MSCU7654321", "MSCU9876543"]
  }
}
isf5RequirementDetected
{
  "context": {
    "status": "LOADED",
    "originPort": { "name": "Shanghai", "unlocode": "CNSHA" },
    "destinationPort": { "name": "Los Angeles", "unlocode": "USLAX" },
    "vessel": { "name": "EVER ACE", "imo": "9893890" },
    "voyageNumber": "1234E"
  }
}

Common Use Cases

Use CaseHow to Implement
Cargo roll alertingFilter for exceptionName = rolledCargo. Notify stakeholders about the new vessel and revised ETA.
Demurrage preventionFilter for exceptionName = demurrageRisk. Trigger pickup scheduling before LFD to avoid charges.
Hold escalationFilter for exceptionName = activeHold. Escalate to customs broker or freight forwarder for resolution.
ISF filing automationFilter for exceptionName = isf5RequirementDetected. Automatically initiate ISF-5 filing with customs broker.
Empty return trackingFilter for exceptionName = streetDwell. Alert drayage teams when containers are dwelling on the street and approaching detention LFD.
Split cargo monitoringFilter for exceptionName = splitCargo. Notify logistics coordinators that containers from the same booking have diverged.

Workflow Shortcuts

  • "When exception is detected" → container.exceptions.updated (optionally filter by exceptionName)
  • "When a new hold occurs" → container.holds.updated or container.exceptions.updated where exceptionName = activeHold

Updated about 4 hours ago