Tracking

<!-- ⚠️ DO NOT EDIT. Auto-generated from skills/tracking/SKILL.md by scripts/sync.js Edits here will be overwritten on the next sync. To change this content, edit the canonical source and re-run the sync script. -->

Package Tracking

Track by Number

1. 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.
2. Call GetTrack with carrier and tracking_number.
3. Key response fields: tracking_status (status, status_details, status_date, location), tracking_history, eta.
4. 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.
5. 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:

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

1. Get the user's HTTPS webhook URL.
2. Call createWebhook with url and event: track_updated.
3. 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