Guides
Guides

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": { /* full container snapshot — see GET /v1/containers/{containerId} */ },
  "changes": {
    "holds": {
      "previous": [
        {
          "type": "LINE",
          "code": "FREIGHT",
          "reportedAt": "2026-07-08T12:15:00.000Z"
        }
      ],
      "current": [
        {
          "type": "LINE",
          "code": "FREIGHT",
          "reportedAt": "2026-07-08T12:15:00.000Z",
          "resolvedAt": "2026-07-14T18:42:17.000Z"
        },
        {
          "type": "CUSTOMS",
          "code": "7H",
          "reportedAt": "2026-07-14T09:03:11.000Z"
        }
      ]
    }
  },
  "deliveryAttempt": 1,
  "pendingRetries": 4,
  "sentAt": "2026-07-14T18:45:02.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

FieldDescription
typeHold category. One of TERMINAL, CUSTOMS, LINE, USDA, USCG, FDA, DHS, UNKNOWN
codeSpecific hold reason (e.g. 1H, 7H, FREIGHT, CTF, IN BOND, INTENSIVE EXAM)
reportedAtISO 8601 timestamp when the hold was first reported to OpenTrack
resolvedAtISO 8601 timestamp when the hold was lifted. Absent (or null) while the hold is still active
remarksFree-text detail from the source (optional)
amountDueAmount in the account's currency required to resolve the hold (optional; typically only present on LINE/TERMINAL fee-type holds)
📘

Enhanced Customs Visibility

Additional customs hold types (CBPA, OGA, AMS, APHIS, FSIS, EPA, and more) and granular ACE Appendix D disposition codes (e.g. 1G, 1S, 1T, 1U, 1R, 5H, 2Z, A3, 71, 73, 77) are available with the Enhanced Customs Visibility add-on, which sources data directly from OpenTrack's integration with U.S. CBP.

changes object

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

Hold lifecycle

A hold's identity is defined by its type + code. When a previously-reported hold is lifted, OpenTrack does not remove it from the holds array — instead, the same hold record is emitted again with a resolvedAt timestamp populated. This means:

  • Active hold → the hold appears in current with reportedAt set and resolvedAt absent (or null).
  • Resolved hold → the hold appears in current with the same type + code as before, reportedAt unchanged, and resolvedAt now populated.

To detect resolution: for each hold in changes.holds.current, check whether resolvedAt is now set on a hold that previously had no resolvedAt in changes.holds.previous.

Common Use Cases

Use CaseHow to Implement
New hold alertCompare changes.holds.previous and changes.holds.current to find newly added holds. Alert the customs team or broker immediately.
Hold resolved notificationDetect when a hold gains a resolvedAt value to notify drayage operations that the container may now be available for pickup
Customs hold resolver workflowTrigger an automated workflow when a customs hold (type = CUSTOMS) is detected. Initiate follow-up with the customs broker to resolve the hold.
Demurrage risk assessmentWhen a new hold is placed, evaluate its impact on demurrage exposure by comparing with LFD and current availability status
Compliance trackingLog 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 18 days ago

Did this page help you?