whereparcel

Stuck on integration? Have a question? The developer is standing by.

Tutorial 9 min read

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:

  1. Verify the signature — every webhook includes an X-WhereParcel-Signature header. Compute the HMAC-SHA256 of the raw body using your webhook secret and reject mismatches.
  2. 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/else ladder
  • 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

SymptomLikely causeFix
401 UnauthorizedMissing the Bearer prefix or the secret keySend Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY
429 Too Many RequestsBurst exceeded plan rate limitAdd exponential backoff or upgrade plan
Status stuck on pendingCarrier hasn’t scanned the parcel yetPoll or re-check after several hours; not an API issue
400 INVALID_CARRIERCarrier code missing or misspelledUse a code from GET /v2/carriers, or find it with POST /v2/detect
Webhook not firingWrong URL, dev server unreachable, or event filter excludes the changeCheck dashboard logs and signature verification

Next Steps

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 →

Tags: #setup #tutorial #integration #guide #examples #developers #webhooks