---
updatedAt: 2026-06-25T15:18:16.000Z
agentTools:
projectIndex: https://developers.opentrack.co/llms.txt
---
# 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 Name | When It Fires |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `rolledCargo` | The container was rolled to a different vessel, detected via vessel and/or ETA changes |
| `advancedCargo` | The container was moved to a different vessel with an earlier ETA, detected via vessel and ETA changes |
| `demurrageRisk` | The container is at risk of incurring demurrage charges (approaching or past LFD) |
| `demurrageDetected` | Demurrage charges have been detected on the container |
| `activeHold` | An active hold is preventing container release |
| `railDwell` | The container has been dwelling at a rail facility longer than expected |
| `streetDwell` | The container has been on the street (outgated but not returned empty) longer than expected |
| `noRailSightings` | A rail-bound container has not had any rail sightings within the expected window |
| `splitCargo` | Containers on the same booking are on different vessels or have diverging timelines |
| `isf5RequirementDetected` | An 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:
```json
{
"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
```json
{
"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"
}
}
```
advancedCargo
```json
{
"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-22T00:00:00.000Z",
"currentEta": "2025-07-15T00:00:00.000Z"
}
}
```
demurrageRisk
```json
{
"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
```json
{
"context": {
"status": "AVAILABLE",
"demurrageOwedAtPort": 275.50,
"demurrageOwedAtRailStation": null,
"isRailMove": false,
"originPort": { "name": "Shanghai", "unlocode": "CNSHA" },
"destinationPort": { "name": "Los Angeles", "unlocode": "USLAX" }
}
}
```
activeHold
```json
{
"context": {
"status": "DISCHARGED",
"holds": [
{ "type": "CUSTOMS", "code": "1H", "reportedAt": "2025-07-10" }
],
"originPort": { "name": "Shanghai", "unlocode": "CNSHA" },
"destinationPort": { "name": "Los Angeles", "unlocode": "USLAX" }
}
}
```
railDwell
```json
{
"context": {
"status": "ARRIVED_AT_RAIL_FACILITY",
"originPort": { "name": "Shanghai", "unlocode": "CNSHA" },
"destinationPort": { "name": "Chicago", "unlocode": "USCHI" },
"dischargedDate": "2025-07-05T00:00:00.000Z"
}
}
```
streetDwell
```json
{
"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
```json
{
"context": {
"status": "LOADED_ON_RAIL",
"lastKnownPositionDate": "2025-07-08T00:00:00.000Z",
"originPort": { "name": "Los Angeles", "unlocode": "USLAX" },
"destinationPort": { "name": "Chicago", "unlocode": "USCHI" }
}
}
```
splitCargo
```json
{
"context": {
"status": "LOADED",
"originPort": { "name": "Shanghai", "unlocode": "CNSHA" },
"destinationPort": { "name": "Los Angeles", "unlocode": "USLAX" },
"siblingContainers": ["MSCU7654321", "MSCU9876543"]
}
}
```
isf5RequirementDetected
```json
{
"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 Case | How to Implement |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Cargo roll alerting** | Filter for `exceptionName` = `rolledCargo`. Notify stakeholders about the new vessel and revised ETA. |
| **Demurrage prevention** | Filter for `exceptionName` = `demurrageRisk`. Trigger pickup scheduling before LFD to avoid charges. |
| **Hold escalation** | Filter for `exceptionName` = `activeHold`. Escalate to customs broker or freight forwarder for resolution. |
| **ISF filing automation** | Filter for `exceptionName` = `isf5RequirementDetected`. Automatically initiate ISF-5 filing with customs broker. |
| **Empty return tracking** | Filter for `exceptionName` = `streetDwell`. Alert drayage teams when containers are dwelling on the street and approaching detention LFD. |
| **Split cargo monitoring** | Filter 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`