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
1---2name: tracking-23description: Track packages across carriers, view tracking history, and set up tracking webhooks via the Shippo API4---5<!--6 ⚠️ DO NOT EDIT. Auto-generated from skills/tracking/SKILL.md by scripts/sync.js7 Edits here will be overwritten on the next sync.8 To change this content, edit the canonical source and re-run the sync script.9-->101112# Package Tracking1314## Track by Number15161. 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.172. Call `GetTrack` with `carrier` and `tracking_number`.183. Key response fields: `tracking_status` (status, status_details, status_date, location), `tracking_history`, `eta`.194. 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.205. Present: current status, location, ETA, substatus details, and chronological event history (most recent first).2122---2324## Status Values2526See `shippo/references/carrier-guide.md` for carrier-specific status nuances. Standard values:2728| Status | Meaning |29|---|---|30| PRE_TRANSIT | Label created, carrier has not received the package |31| TRANSIT | Package is in transit |32| DELIVERED | Delivered |33| RETURNED | Being returned or returned to sender |34| FAILURE | Delivery failed |35| UNKNOWN | No tracking information from carrier |3637The `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.3839---4041## Find Trackable Packages4243Call `ListTransactions`. Filter for `object_status: SUCCESS`. Each successful transaction has `tracking_number` and carrier info. Then call `GetTrack` for selected items.4445---4647## Register a Tracking Webhook48491. Get the user's HTTPS webhook URL.502. Call `createWebhook` with `url` and `event: track_updated`.513. Optionally call `CreateTrack` with carrier and tracking number to register a specific shipment for push updates.5253---5455## Quick Reference5657**Track a package:**58`GetTrack` with carrier + tracking number5960**Find past shipment tracking:**61`ListTransactions` -> filter SUCCESS -> `GetTrack`
goshippo