package-tracker

name	package-tracker
description	Track packages and shipments via the 17track API. Use when the user asks to track a package, check delivery status, add a tracking number, list tracked shipments, or get updates on deliveries. Supports 2000+ carriers worldwide with auto carrier detection and tracking URLs.

Package Tracker

Track packages via the 17track universal API. Supports FedEx, UPS, DHL, CTT, China Post, Royal Mail, USPS, and 2000+ other carriers with automatic carrier detection.

Setup

Run once from the skill directory:

cd /root/.openclaw/workspace/skills/package-tracker
bash scripts/setup.sh

Then edit scripts/.env to add your API key:

SEVENTEEN_TRACK_API_KEY=your_key_here

Get a free key at https://admin.17track.net (100 registrations/month, unlimited status checks).

Usage

All commands run from the skill directory. Activate the venv first:

cd /root/.openclaw/workspace/skills/package-tracker
source scripts/venv/bin/activate

Add a Package

python scripts/cli.py add "TRACKING_NUMBER" -d "Description of contents"

• Carrier is auto-detected from the tracking number format
• Override with -c "FedEx" if needed
• Uses 1 registration from monthly quota (100/month free)
• Returns a tracking URL for the detected carrier

Check for Updates

python scripts/cli.py check

• Queries 17track for all active packages
• Prints status changes and new tracking events
• Outputs notifications to stdout for OpenClaw to relay via native messaging
• gettrackinfo calls are free and unlimited

List Packages

python scripts/cli.py list          # Active only
python scripts/cli.py list --all    # Include delivered/inactive

Package Details

python scripts/cli.py details "TRACKING_NUMBER"

Shows full tracking history with all events, locations, and timestamps.

Remove a Package

python scripts/cli.py remove "TRACKING_NUMBER"

Deactivates tracking (does not delete history).

Check API Quota

python scripts/cli.py quota

Shows registrations used this month vs. the 100/month free limit.

Cron Integration

Set up periodic checks with cron or OpenClaw heartbeats.

Using cron (every 3 hours)

# Add to crontab:
0 */3 * * * cd /root/.openclaw/workspace/skills/package-tracker && scripts/venv/bin/python scripts/check_updates.py --quiet

Using OpenClaw heartbeat

In your heartbeat logic, include:

cd /root/.openclaw/workspace/skills/package-tracker
source scripts/venv/bin/activate
python scripts/check_updates.py

The check_updates.py script:

• Checks all active packages for updates
• Prints notifications to stdout for OpenClaw to relay
• Exits 0 on success, 1 on error
• Use --quiet to suppress output when there are no updates

Notifications

When updates are detected, the tracker outputs formatted notifications to stdout. OpenClaw reads this output and relays it via its native message tool — which works on Telegram, Signal, Discord, WhatsApp, or whatever channel the user has configured.

Tracking URLs

Every package gets a carrier-specific tracking URL:

Carrier	URL Pattern
FedEx	fedex.com/fedextrack/?trknbr={tn}
UPS	ups.com/track?tracknum={tn}
DHL	dhl.com/en/express/tracking.html?AWB={tn}
CTT	ctt.pt/.../objectSearch.jspx?objects={tn}
USPS	tools.usps.com/go/TrackConfirmAction?tLabels={tn}
Fallback	t.17track.net/en#nums={tn}

The get_tracking_url(tracking_number, carrier) function in tracker.py generates these.

Status Codes

Status	Emoji	Meaning
pending	⏳	Just added, not yet checked
Not Found	❓	17track has no data yet
In Transit	🚚	Package is moving
Pick Up	📬	Ready for pickup
Delivered	✅	Delivered (auto-deactivated)
Undelivered	⚠️	Delivery attempt failed
Expired	⌛	Tracking data expired
Alert	🚨	Exception or issue

Delivered packages are automatically deactivated.

Data Storage

• Database: scripts/data/tracker.db (SQLite)
• Tables: packages, tracking_events, api_usage
• All data is local. Nothing is sent externally except 17track API calls.

Environment Variables

Variable	Required	Description
SEVENTEEN_TRACK_API_KEY	Yes	17track API key from admin.17track.net

Troubleshooting

• "API key not set" — Edit scripts/.env and add your 17track key
• "Monthly limit reached" — Free tier is 100 registrations/month. Wait or upgrade.
• No carrier detected — Pass -c "CarrierName" when adding, or let 17track auto-detect (carrier code 0)

References

• references/carriers.md — Full list of supported carriers with patterns and URLs
• references/17track-api.md — API endpoint reference, status codes, rate limits