Tracking

Track any shipment across all supported carriers using a single API call. FlexOps normalizes tracking events from every carrier into a consistent format.

Shipment lifecycle

Every shipment follows this state machine. FlexOps fires webhook events at each transition:

Get tracking status

curl -X GET https://api.flexops.io/v1/tracking/9400111899223456789012 \
  -H "X-API-Key: your-api-key"

{
  "trackingNumber": "9400111899223456789012",
  "carrier": "usps",
  "status": "in_transit",
  "estimatedDelivery": "2026-03-12T17:00:00Z",
  "events": [
    {
      "timestamp": "2026-03-10T14:30:00Z",
      "status": "in_transit",
      "description": "Arrived at USPS Regional Facility",
      "location": {
        "city": "Salt Lake City",
        "state": "UT",
        "country": "US"
      }
    },
    {
      "timestamp": "2026-03-10T08:00:00Z",
      "status": "accepted",
      "description": "Accepted at USPS Origin Facility",
      "location": {
        "city": "Denver",
        "state": "CO",
        "country": "US"
      }
    }
  ]
}

Tracking statuses

Status	Description	Webhook event
pre_transit	Label created, not yet scanned	label.created
accepted	Carrier has accepted the package	tracking.updated
in_transit	Package is moving through the network	tracking.updated
out_for_delivery	On the delivery vehicle	tracking.updated
delivered	Successfully delivered	tracking.delivered
failed_attempt	Delivery attempted but unsuccessful	tracking.exception
returned	Package is being returned to sender	tracking.updated
exception	Issue with delivery (held, damaged, etc.)	tracking.exception

Carrier-specific notes

Carrier detection

FlexOps auto-detects the carrier from the tracking number format. You can also pass ?carrier=usps to skip auto-detection for faster responses.

Carrier	Tracking number format	Update frequency
USPS	20-34 digits	Every 1-4 hours
FedEx	12-15 digits	Every 30-60 minutes
UPS	1Z + 16 alphanumeric	Every 15-30 minutes
DHL	10 digits	Every 2-6 hours
Canada Post	16 digits	Every 2-4 hours

Webhook notifications

Instead of polling, subscribe to tracking webhooks to receive real-time updates. See Webhooks.