shipment.tracking.failed

Overview

Fired when OpenTrack is unable to locate a shipment (master bill of lading) after repeated tracking attempts. This event indicates that the master bill number could not be found at the specified carrier, and shipment-level tracking has not successfully started.

When This Event Fires

The master bill has been submitted for tracking, but after multiple attempts, the carrier's system does not recognize the bill of lading number. The event includes information about how many attempts remain before tracking is permanently abandoned.

📘
This event operates at the shipment level (master bill of lading), not at the individual container level. For container-level tracking failures, see container.tracking.failed.

Payload Structure

{
  "event": "shipment.tracking.failed",
  "data": {
    "shipment": {
      "number": "MEDU1234567",
      "referenceNumbers": ["PO-12345", "REF-67890"]
    },
    "trackingAttempts": 5,
    "attemptsRemaining": 0,
    "account": {
      "region": "US",
      "domain": "example.com"
    }
  },
  "deliveryAttempt": 1,
  "pendingRetries": 4,
  "sentAt": "2025-07-19T17:00:00.654Z"
}

`data` object fields

Field	Description
`shipment.number`	The master bill of lading number that failed to track
`shipment.referenceNumbers`	Array of customer reference numbers associated with the shipment
`trackingAttempts`	Number of tracking attempts made so far
`attemptsRemaining`	Number of remaining attempts before tracking is permanently stopped
`account.region`	Account region
`account.domain`	Account domain

Common Use Cases

Use Case	How to Implement
BOL verification alert	Notify the team that the master bill number may be incorrect or the carrier may not yet have the booking in their system
Retry logic	If `attemptsRemaining` > 0, the system will continue trying. If 0, consider prompting the user to verify the BOL number and re-submit.
Onboarding data quality	Track failed shipment tracking rates per customer to identify data quality issues during onboarding
Fallback workflow	When tracking fails, trigger a manual lookup or alternative data source workflow

Updated about 4 hours ago