Parcel Tracking API Setup Guide: Multi-Carrier Tracking in 5 Minutes (with Code Examples)
Step-by-step setup guide for the WhereParcel parcel tracking API. Sign up, first request, auto-detection, webhooks, and a production checklist with cURL, Node.js, Python, and Go examples.
WhereParcel Team
This is a focused setup guide for the WhereParcel multi-carrier tracking API. The goal: from zero to a working production-shaped integration in five minutes, with code examples in four languages and a clear production checklist at the end.
If you just want a TL;DR, jump to the setup checklist at the bottom.
What You’ll Have at the End
- An API key tested against a live request
- A multi-carrier lookup that works across USPS, UPS, FedEx, DHL, and the rest of our 39+ live carriers (more on request)
- Auto-detection so you don’t hardcode carrier names
- A webhook listener for push status updates
- A production-ready error and retry pattern
Step 1 — Sign Up and Get Your Key (1 min)
Go to console.whereparcel.com, sign up with email, and open your dashboard.
Create a new API key from console.whereparcel.com. You get two values — an API key and a secret key — and every request sends both, joined by a colon:
Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY
Treat it like a password. Never put it in client-side JavaScript or commit it to a public repo. Use environment variables:
export WP_API_KEY="YOUR_API_KEY:YOUR_SECRET_KEY" # key and secret, joined by a colon
Your plan is active as soon as you subscribe, so you can test against the real API right away — and you can cancel anytime, keeping access until the end of your billing period. Once you are a customer, the ambassador program can extend that — paying customers who write a short post get 3 months of Starter free.
Step 2 — Your First Tracking Request (2 min)
The single endpoint you need is POST /v2/track. Pick the language you actually use.
cURL
curl -X POST https://api.whereparcel.com/v2/track \
-H "Authorization: Bearer $WP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"trackingItems": [
{ "carrier": "us.usps", "trackingNumber": "9400111899223197428490" }
]
}'
Node.js (fetch)
const res = await fetch('https://api.whereparcel.com/v2/track', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.WP_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
trackingItems: [
{ carrier: 'us.usps', trackingNumber: '9400111899223197428490' },
],
}),
});
const data = await res.json();
console.log(data);
Python (requests)
import os, requests
res = requests.post(
'https://api.whereparcel.com/v2/track',
headers={'Authorization': f"Bearer {os.environ['WP_API_KEY']}"},
json={
'trackingItems': [
{'carrier': 'us.usps', 'trackingNumber': '9400111899223197428490'}
]
},
)
print(res.json())
Go (net/http)
body := strings.NewReader(`{
"trackingItems": [
{"carrier": "us.usps", "trackingNumber": "9400111899223197428490"}
]
}`)
req, _ := http.NewRequest("POST", "https://api.whereparcel.com/v2/track", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("WP_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
What You Get Back
{
"success": true,
"data": [
{
"carrier": "us.usps",
"trackingNumber": "9400111899223197428490",
"status": "success",
"data": {
"deliveryStatus": "out_for_delivery",
"events": [
{
"timestamp": "2026-05-04T12:00:00Z",
"status": "out_for_delivery",
"location": "Los Angeles, CA",
"description": "Out for delivery"
}
],
"lastUpdated": "2026-05-04T12:00:00Z"
},
"billable": true,
"cached": false
}
],
"summary": {
"total": 1,
"success": 1,
"failed": 0,
"usageIncremented": 1
}
}
The schema is identical across all 39+ live carriers (and new ones added on request). Status enums are normalized — no more switching on each carrier’s quirky strings.
Step 3 — Carrier Detection (3 min)
You usually don’t know which carrier owns a number until you ask. POST /v2/detect matches it against the formats of every live carrier — free, with no carrier lookup — and returns the candidates with a specificityScore. Track with the highest one:
async function trackAny(trackingNumber) {
const headers = { 'Authorization': `Bearer ${process.env.WP_API_KEY}`, 'Content-Type': 'application/json' };
const detect = await fetch('https://api.whereparcel.com/v2/detect', {
method: 'POST', headers, body: JSON.stringify({ trackingNumber }),
}).then((r) => r.json());
const [best] = detect.data.candidates.sort((a, b) => b.specificityScore - a.specificityScore);
if (!best) throw new Error('Unknown tracking number format');
return fetch('https://api.whereparcel.com/v2/track', {
method: 'POST', headers,
body: JSON.stringify({ trackingItems: [{ carrier: best.code, trackingNumber }] }),
}).then((r) => r.json());
}
await trackAny('1Z999AA10123456784'); // → us.ups
await trackAny('EE123456785US'); // → us.usps
Once you have the carrier code, the response is the same shape for every carrier — there’s no per-carrier branching code in your codebase.
You can also batch up to 5 numbers per request, which is the right move for any background job that processes recent shipments in bulk.
Step 4 — Webhooks for Push Updates (4 min)
Polling every shipment every hour is wasteful and slow. Webhooks reverse the flow: WhereParcel calls you when a shipment’s status changes.
Register Your Webhook
In the dashboard, add an endpoint URL like https://yourapp.com/webhooks/whereparcel and pick the events you care about (status changes, delivered, exceptions).
Receive It
// Express example
app.post('/webhooks/whereparcel', express.json(), (req, res) => {
const { trackingNumber, carrier, status, events } = req.body;
// Persist the update
await db.shipments.update({ trackingNumber }, { status, events });
res.status(200).send('ok');
});
Two production essentials:
- Verify the signature — every webhook includes an
X-WhereParcel-Signatureheader. Compute the HMAC-SHA256 of the raw body using your webhook secret and reject mismatches. - Respond 2xx fast — do the heavy work in a queue. WhereParcel sends each webhook once and doesn’t retry, so a slow or failing handler can miss an update.
Step 5 — Production Checklist (5 min)
A working request is not a working integration. Run through this before you ship:
- API key in env vars only. Never in source, never in front-end bundles
- Auto-detection in place so you don’t have a per-carrier
if/elseladder - Idempotency keys on any code path that creates shipments
- Webhook signature verification
- Webhook handler queues work rather than blocking on heavy DB writes
- Polling fallback for environments where you can’t receive webhooks
- Rate-limit aware retries — Starter is 30 req/min, Pro is 60, Business is 200; back off on 429
- Status enum mapping to your internal model (e.g.
in_transit→SHIPPED_IN_PROGRESS) - Error logging with the request ID that the API returns in headers
- Sandbox vs production keys kept in separate environments
Common Issues and How to Fix Them
| Symptom | Likely cause | Fix |
|---|---|---|
| 401 Unauthorized | Missing the Bearer prefix or the secret key | Send Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY |
| 429 Too Many Requests | Burst exceeded plan rate limit | Add exponential backoff or upgrade plan |
Status stuck on pending | Carrier hasn’t scanned the parcel yet | Poll or re-check after several hours; not an API issue |
400 INVALID_CARRIER | Carrier code missing or misspelled | Use a code from GET /v2/carriers, or find it with POST /v2/detect |
| Webhook not firing | Wrong URL, dev server unreachable, or event filter excludes the change | Check dashboard logs and signature verification |
Next Steps
- Full API reference — every endpoint, every response field
- Best Parcel Tracking API 2026 Comparison — how WhereParcel compares to AfterShip, 17TRACK, Tracktry, and Parcellab
- Webhook best practices
- API rate limiting best practices
If you got stuck anywhere in the five minutes, ping support from the dashboard — we usually answer same-day.
Can't find your carrier? We add new carriers on request — just let us know.
Request a carrier →Got a question? Just ask. Drop by our Discord — the developer behind WhereParcel reads every message and replies personally. No bots, no tickets, just a real conversation.
Join Discord → Join Slack →