Logistics Tracker

Query shipping status for mainstream European and American carriers from a tracking number.

Trigger Conditions

Invoke when the user:

• Pastes a tracking number (alone or with carrier context)
• Says "track my package / order / shipment"
• Asks about delivery status, parcel location, or estimated arrival
• Provides a number and asks "where is it?"

Step 1 — Identify the Carrier

Match the tracking number against these patterns in order (most-specific first):

If the format is ambiguous (e.g., a plain 12-digit number could be FedEx or DHL), ask the user to confirm the carrier or try both.

Step 2 — Fetch Tracking Data

Track123 API

Track123 supports 1700+ carriers. Call the Track123 REST API via Bash.

API Key Setup (first time only)

If the curl commands below still contain $TRACK123_API_KEY, ask the user to visit https://www.track123.com/api → Dashboard → API tab → copy and paste the key here. Once received, replace $TRACK123_API_KEY in this skill file with the actual key value.

Step A — Register the tracking number:

curl -s -X POST "https://api.track123.com/gateway/open-api/tk/v2/track/import" \
  -H "Track123-Api-Secret: $TRACK123_API_KEY" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -d '[{"trackNo": "{number}"}]'

Step B — Query the tracking status:

curl -s -X POST "https://api.track123.com/gateway/open-api/tk/v2/track/query" \
  -H "Track123-Api-Secret: $TRACK123_API_KEY" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -d '{"trackNos": ["{number}"]}'

Parse the JSON response (data.accepted.content[0]) and extract:

• transitStatus — overall status (e.g. DELIVERED, IN_TRANSIT)
• deliveredTime / lastTrackingTime — last update timestamp
• localLogisticsInfo.trackingDetails — events array (most recent first), each with eventTime, address, eventDetail
• expectedDeliveryTime — estimated delivery window
• localLogisticsInfo.courierTrackingLink — direct tracking URL

Present using the Step 3 format.

Step 3 — Present Results

Format the response in this structure:

📦 Tracking: {NUMBER}
🚚 Carrier: {CARRIER NAME}
📍 Status: {CURRENT STATUS}  ← e.g., "In Transit", "Out for Delivery", "Delivered"
🕐 Last Update: {DATE TIME TIMEZONE}
📍 Last Location: {CITY, STATE/COUNTRY}

--- Tracking History ---
[Most recent first]
• {DATE TIME} — {LOCATION} — {EVENT DESCRIPTION}
• {DATE TIME} — {LOCATION} — {EVENT DESCRIPTION}
• {DATE TIME} — {LOCATION} — {EVENT DESCRIPTION}
  ... (truncate to 10 events max if many)

📅 Estimated Delivery: {DATE or "Not available"}
🔗 Track online: {DIRECT TRACKING URL}

Status icons:

• ✅ Delivered
• 🚚 Out for Delivery
• 📦 In Transit
• 🛃 Customs Clearance
• ⏳ Pre-Shipment / Label Created
• ⚠️ Exception / Delay / Attempted Delivery
• ❓ Unknown / No Data Found

Step 4 — Handle Multiple Tracking Numbers

If the user pastes multiple tracking numbers at once:

1. Process all in parallel (separate WebSearch per number)
2. Present a summary table first:

| # | Tracking Number       | Carrier | Status          | Est. Delivery |
|---|----------------------|---------|-----------------|---------------|
| 1 | 1Z999AA10123456784   | UPS     | In Transit      | Jun 5, 2026   |
| 2 | 123456789012         | FedEx   | Delivered       | Jun 1, 2026   |

Then provide full details for each below.

Step 5 — Edge Cases

No tracking data found:

> I searched for tracking number {number} with {carrier} but couldn't find any results. This can happen when:

> - The label was created but the package hasn't been scanned yet (pre-shipment)

> - The tracking number was entered incorrectly

> - It's an older shipment (>120 days)

>

> Try checking directly: {DIRECT TRACKING URL}

Ambiguous carrier:

> This number ({number}) could match multiple carriers. Could you tell me which one shipped your package?

> - FedEx (12-digit)

> - DHL Express (10-digit)

>

> Or I can check both for you.

Carrier not covered:

If the pattern doesn't match any known carrier, search broadly:

track package "{number}"

and report the carrier identified by the search results.

Carrier Cheat Sheet (Quick Reference)

When a user mentions a European country, prefer that country's local carriers if the number pattern fits.