Package Tracking
Track by Number
- Determine carrier and tracking number. Carrier must be a lowercase Shippo token (e.g.,
usps, ups, fedex, dhl_express). See shippo/references/carrier-guide.md for tracking number format hints per carrier. If uncertain, ask the user.
- Call
GetTrack with carrier and tracking_number.
- Key response fields:
tracking_status (status, status_details, status_date, location), tracking_history, eta.
- Each tracking event includes a
substatus object with code, text, and action_required (boolean). Include substatus details when presenting tracking history -- these provide more specific information about what happened at each step.
- Present: current status, location, ETA, substatus details, and chronological event history (most recent first).
Status Values
See shippo/references/carrier-guide.md for carrier-specific status nuances. Standard values:
| Status |
Meaning |
| PRE_TRANSIT |
Label created, carrier has not received the package |
| TRANSIT |
Package is in transit |
| DELIVERED |
Delivered |
| RETURNED |
Being returned or returned to sender |
| FAILURE |
Delivery failed |
| UNKNOWN |
No tracking information from carrier |
The eta field is provided by most major carriers (USPS, UPS, FedEx, DHL Express) but availability is carrier-dependent, it may be null for regional carriers or for shipments before the carrier has finalized routing. Treat absence as informational, not as an error condition.
Find Trackable Packages
Call ListTransactions. Filter for object_status: SUCCESS. Each successful transaction has tracking_number and carrier info. Then call GetTrack for selected items.
Register a Tracking Webhook
- Get the user's HTTPS webhook URL.
- Call
createWebhook with url and event: track_updated.
- Optionally call
CreateTrack with carrier and tracking number to register a specific shipment for push updates.
Quick Reference
Track a package:
GetTrack with carrier + tracking number
Find past shipment tracking:
ListTransactions -> filter SUCCESS -> GetTrack
