---
updatedAt: 2026-03-16T16:23:29.000Z
agentTools:
  projectIndex: https://developers.opentrack.co/llms.txt
---

# customs.entry.status.updated

## Overview

Fired when there is a status update on a US Customs and Border Protection (CBP) entry associated with a shipment. This event provides real-time customs clearance updates including holds, releases, and activity messages from CBP.

## When This Event Fires

OpenTrack's CBP integration has received and processed a new customs entry status response. This occurs when:

* A new CBP activity is recorded (e.g. entry summary filed, examination ordered)
* A customs hold is placed or released
* A release is granted (e.g. conditional release, full release)

## Payload Structure

```json
{
  "event": "customs.entry.status.updated",
  "data": {
    "shipment": {
      "number": "MEDU1234567",
      "masterBillNumber": "MEDU1234567",
      "bookingNumber": "BK12345",
      "referenceNumbers": ["PO-12345"]
    },
    "account": {
      "domain": "example.com",
      "region": "US"
    },
    "activities": [
      {
        "date": "2025-07-15T00:00:00.000Z",
        "message": "Entry Summary Accepted",
        "releaseDate": "2025-07-16T00:00:00.000Z",
        "releaseOrigin": "CBP",
        "quantity": "1",
        "isHold": false,
        "code": "ESA"
      }
    ]
  },
  "deliveryAttempt": 1,
  "pendingRetries": 4,
  "sentAt": "2025-07-19T17:00:00.654Z"
}
```

> ⚠️ The `data` payload for this event is customs-specific — it is **not** the full container snapshot. It includes shipment identifiers, account context, and an array of CBP activities.

### `data.activities` array fields

| Field           | Description                                                       |
| --------------- | ----------------------------------------------------------------- |
| `date`          | Date of the CBP activity                                          |
| `message`       | Human-readable description of the activity                        |
| `releaseDate`   | Release date, if applicable                                       |
| `releaseOrigin` | Origin of the release (e.g. `CBP`)                                |
| `quantity`      | Quantity associated with the activity                             |
| `isHold`        | Whether this activity represents a hold (`true`) or not (`false`) |
| `code`          | CBP activity code                                                 |

## Common Use Cases

| Use Case                          | How to Implement                                                                                     |
| --------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Customs clearance tracking**    | Monitor the `activities` array for release events to know when cargo is customs-cleared              |
| **Hold detection and escalation** | Filter `activities` where `isHold` = `true` to detect customs holds and escalate to the broker       |
| **Automated ISF follow-up**       | When a customs entry status indicates a filing requirement, trigger downstream ISF filing workflows  |
| **Compliance dashboard**          | Display real-time customs status for all active shipments, showing held vs. cleared entries          |
| **Drayage coordination**          | Use customs release events as a signal to dispatch drayage when combined with container availability |