container.holds.updated

Overview

Fired when the holds on a container change — either a new hold is placed or an existing hold is resolved. Holds include customs holds, freight holds, carrier holds, USDA holds, and other regulatory or commercial holds that can prevent container release.

When This Event Fires

The system detects a difference in the holds array between the previous and current container snapshot. This means:

A new hold has been reported (e.g. customs hold placed on the container)
An existing hold has been resolved (e.g. resolvedAt date has been set)
Hold details have been updated (e.g. remarks changed, amount due updated)

Payload Structure

{
  "event": "container.holds.updated",
  "data": { /* IContainerVoyageResponse — full container snapshot */ },
  "changes": {
    "holds": {
      "previous": [
        { "type": "CUSTOMS", "code": "1H", "reportedAt": "2025-07-10" }
      ],
      "current": [
        { "type": "CUSTOMS", "code": "1H", "reportedAt": "2025-07-10" },
        { "type": "FREIGHT", "code": "7H", "reportedAt": "2025-07-12" }
      ]
    }
  },
  "deliveryAttempt": 1,
  "pendingRetries": 4,
  "sentAt": "2025-07-19T17:00:00.654Z"
}

`data` object

The full current state of the container. The holds array within data contains all current holds with their statuses.

Hold object fields

Field	Description
`type`	Hold type (e.g. `CUSTOMS`, `FREIGHT`, `CARRIER`, `USDA`, `FDA`, `OTHER`)
`code`	Hold code (e.g. `1H`, `7H`)
`reportedAt`	When the hold was reported
`resolvedAt`	When the hold was resolved (null if still active)
`remarks`	Additional details about the hold
`amountDue`	Amount due to resolve the hold (if applicable)

`changes` object

Contains { previous, current } for the holds array, showing the full before and after state.

Common Use Cases

Use Case	How to Implement
New hold alert	Compare `changes.holds.previous` and `changes.holds.current` to find newly added holds. Alert the customs team or broker immediately.
Hold resolved notification	Detect when a hold gains a `resolvedAt` value to notify drayage operations that the container may now be available for pickup
Customs hold resolver workflow	Trigger an automated workflow when a customs hold (`type` = `CUSTOMS`) is detected. Initiate follow-up with the customs broker to resolve the hold.
Demurrage risk assessment	When a new hold is placed, evaluate its impact on demurrage exposure by comparing with LFD and current availability status
Compliance tracking	Log all hold events for regulatory compliance auditing, especially for FDA, USDA, and customs holds

Workflow Shortcuts

"When a new hold occurs" → container.holds.updated where a new entry appears in the holds array, optionally filtered by hold.type

Updated about 4 hours ago