whereparcel

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

Guide 10 min read

Shipment Tracking API: How It Works & How to Choose (2026)

What a shipment tracking API does, how carrier data becomes one JSON format, and an 8-point checklist for choosing a package tracking API in 2026.

WhereParcel Team

A shipment tracking API lets your software ask “where is this parcel?” and get a structured answer back — the current status, a list of scan events, and timestamps — without a person opening a carrier’s website. You might see the same thing called a package tracking API, parcel tracking API, delivery tracking API or carrier tracking API. They all mean the same job: turn a carrier name and a tracking number into data your code can use.

This guide explains how these APIs work under the hood, what a good response looks like, and the eight questions worth asking before you commit to one. Where we show code, it’s real code against the WhereParcel API — you can copy it.

TL;DR — The Quick Answer

  • A shipment tracking API takes carrier + tracking number and returns a normalized status and event history in one JSON shape, no matter which carrier the parcel is with.
  • There are two ways to get updates: ask on demand (a synchronous request) or register once and receive pushes (webhooks). For anything you track over days, webhooks are cheaper and simpler.
  • When choosing, check: carriers that are actually live for the ones you ship with, the billing unit (request, shipment, or contract), webhook behavior, per-request limits, and how status normalization works.
  • Count your real volume before you compare prices. Polling the same parcel twice a day for ten days is 20 lookups; registering it for push updates can be one.

What a Shipment Tracking API Actually Does

Every carrier exposes tracking differently. USPS, UPS, FedEx and DHL each have their own formats, status vocabularies and access rules, and many regional carriers only publish tracking on a web page. A tracking API sits in the middle and does three things:

  1. Fetches the carrier’s tracking data for a tracking number.
  2. Normalizes it — maps hundreds of carrier-specific wordings (“Arrived at USPS Regional Facility”, “On FedEx vehicle for delivery”) to a small, fixed set of statuses.
  3. Delivers it to you, either as the response to your request or as a push to your server.

The value is in steps 2 and 3. Getting one carrier’s data once is easy. Keeping twenty carriers’ data consistent, current and in one shape — while carriers change their sites, add bot protection and retire old endpoints — is the part teams underestimate. (We wrote about the official-API-versus-web-data trade-off separately.)

How a Request Flows

A synchronous lookup looks like this:

Your app ──POST /v2/track──▶ Tracking API ──▶ Carrier source (API or web)
                                  │
                         normalize events
                                  │
Your app ◀──── one JSON shape ────┘

Here’s the actual request. Authentication is a single header with your API key and secret:

curl -X POST https://api.whereparcel.com/v2/track \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingItems": [
      { "carrier": "us.usps", "trackingNumber": "9400111899562537866361" }
    ]
  }'

And the response:

{
  "success": true,
  "data": [
    {
      "carrier": "us.usps",
      "trackingNumber": "9400111899562537866361",
      "status": "success",
      "data": {
        "deliveryStatus": "delivered",
        "events": [
          {
            "timestamp": "2026-10-01T18:31:00.000Z",
            "status": "delivered",
            "location": "DECATUR, GA 30030",
            "description": "Delivered, Front Door/Porch",
            "rawStatus": "Delivered, Front Door/Porch",
            "rawDescription": "Delivered, Front Door/Porch"
          }
        ],
        "lastUpdated": "2026-10-02T14:05:12.000Z"
      },
      "billable": true,
      "cached": false
    }
  ],
  "summary": { "total": 1, "success": 1, "failed": 0, "usageIncremented": 1 }
}

Three details in that response matter more than they look:

  • data is an array. One request can carry several tracking numbers (up to five on /v2/track), and each item succeeds or fails on its own. Check each item’s status before reading its data.
  • deliveryStatus is always one of nine values: pending, in_transit, out_for_delivery, delivered, failed, returned, cancelled, lost, unknown. Your code can switch on these without knowing anything about the carrier.
  • The carrier’s own words are kept in rawStatus and rawDescription. Show the normalized status in your UI, and keep the raw text for support tickets and edge cases.

Pull vs Push: Polling or Webhooks

There are two ways to stay current on a parcel.

Pull (polling). You call /v2/track on a schedule. It’s simple and fine for one-off lookups — a support agent checking an order, or a “where’s my package” page that loads on demand. But for parcels you follow over days, polling is wasteful: you pay for every check, including the many where nothing changed.

Push (webhooks). You register a parcel once and the API sends updates to your endpoint. With WhereParcel, a recurring registration re-checks the parcel about every 12 hours for up to 10 days and posts the result to your endpoint after every check. The parcel counts once when you register it; the checks after that are free.

curl -X POST https://api.whereparcel.com/v2/webhooks/register \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookEndpointId": "YOUR_ENDPOINT_ID",
    "recurring": true,
    "trackingItems": [
      { "carrier": "us.usps", "trackingNumber": "9400111899562537866361" },
      { "carrier": "us.ups", "trackingNumber": "1Z999AA10123456784" },
      { "carrier": "us.fedex", "trackingNumber": "794644790132" }
    ]
  }'

One registration takes up to 100 tracking numbers. You create the endpoint once (its URL is where we POST) — see the Webhook Endpoints reference — and reuse its id.

Two honest caveats about push, because they shape how you build:

  • Updates arrive on a cycle, not instantly. About every 12 hours is right for keeping an order database in sync; it isn’t a live map. If a customer needs the latest status right now, call /v2/track for that one parcel.
  • Each delivery is attempted once. Your endpoint should answer with a 2xx within 10 seconds. If your server was down, catch up with GET /v2/webhooks/subscriptions/{requestId}/changes rather than waiting for a resend. Our webhook best practices post covers verifying the X-WhereParcel-Signature header and handling failures.

How to Choose a Shipment Tracking API: 8 Questions

1. Are the carriers you ship with actually live?

Carrier counts in marketing copy range from dozens to thousands. What matters is whether your carriers return data reliably today. Ask for the list of carriers that are live — not “supported on request” — and test your real tracking numbers. We publish ours on the carriers page: 39+ live carriers across nine countries plus international, with USPS, UPS, FedEx, DHL and OnTrac covered for US shippers.

2. What is the billing unit?

The same volume costs very different amounts depending on what is counted:

Billing unitWhat one unit isRewards you for
Per requestOne API callFew calls per parcel (push instead of poll)
Per shipmentOne tracking number, however often checkedChecking often
Annual quota / contractPrepaid volumePredictable, steady volume

WhereParcel counts per request on /v2/track (cache hits come back with billable: false), and a webhook registration counts each parcel once. Our 2026 price comparison puts five providers’ models side by side.

3. What exactly happens on push?

“Webhooks included” can mean very different things. Ask: How often is the parcel re-checked? For how long? Is a failed delivery retried, and if not, how do you catch up? Is the payload the full history or only the change? Clear answers here save you a week of debugging later.

4. What are the per-request and per-minute limits?

Look for two numbers: how many tracking numbers fit in one request, and how many requests you can make per minute. Some carriers are slow to look up, so providers may cap them per request. On WhereParcel, /v2/track takes up to five items, but us.usps, us.ups, us.fedex and intl.dhl are limited to one item per request combined — batch those through webhook registration (100 per call) instead. Plan limits are listed in Rate Limits.

5. How is status normalized — and can you still see the raw text?

A fixed status set is what makes a multi-carrier API worth having. Check how many statuses there are, whether exceptions like returns, cancellations and losses are distinct, and whether the carrier’s original wording is preserved. You want both: a small set to code against and the raw description for humans. Our exception handling guide walks through delivery, customs and transit exceptions and how they show up in the data.

6. Can it identify the carrier from the tracking number?

Customers paste tracking numbers without telling you the carrier. A detection endpoint saves you a lookup table. WhereParcel’s POST /v2/detect matches the number’s format and returns candidate carriers, most specific first — it’s pattern matching only, so it’s free and doesn’t count toward usage. You can try the same logic in the browser with the tracking number validator.

7. How does it handle carriers with heavy bot protection?

USPS, UPS and FedEx are where tracking APIs most often fail in practice. Official carrier APIs come with account approvals, quotas and periodic changes (what changed at USPS in 2026), and carrier websites defend against automated traffic. Ask a provider how lookups for these carriers behave when a source is slow or blocked, and what the response looks like when a lookup fails. On WhereParcel a failed lookup is marked as one — status: "error" on /v2/track, "failed" in webhook payloads — rather than coming back as a silent success.

8. Can you start without a sales call?

For most developer teams, self-serve signup, a public price list and month-to-month billing are worth more than a feature you might use later. Check whether you can get an API key today, test against production, and cancel without a contract.

A Quick Cost Check

Say you ship 2,000 parcels a month and want each one tracked until delivery.

  • Polling twice a day for ten days: up to 20 lookups per parcel, so up to 40,000 billable requests a month (fewer if some responses come from cache).
  • Registering each parcel for push updates: 1 billable unit per parcel, so 2,000 a month — with the same parcels re-checked about every 12 hours.

That difference decides which plan you need, and on many providers it decides the price tier. WhereParcel plans start at $49/month for 10,000 requests; the full table is on the pricing section. There’s no free tier, and you can cancel anytime.

Getting Started in Three Calls

  1. Detect the carrier if you don’t know it: POST /v2/detect with the tracking number (free).
  2. Track once to show a status right away: POST /v2/track.
  3. Register for push so you never poll again: POST /v2/webhooks/register with recurring: true.

You can try a lookup without writing code in the API Playground, and test carrier detection in the tracking number validator. For a step-by-step build with Node.js, Python and Go, follow the parcel tracking API setup guide, and keep the Tracking API reference open while you work.

FAQ

Is there a free shipment tracking API?

Some providers offer a free tier with a low monthly cap, which is useful for prototypes. WhereParcel doesn’t have a free tier — plans start at $49/month and you can cancel anytime. Carrier detection (/v2/detect) and the carrier list endpoints are free on every plan.

Which API tracks USPS, UPS and FedEx in one format?

Any multi-carrier tracking API should; the difference is how reliably each carrier returns data and how statuses are normalized. On WhereParcel, all three return the same JSON shape and the same nine delivery statuses as every other carrier.

How often does tracking data update?

On a synchronous request, you get the carrier’s data at the time of the lookup. With recurring webhooks, WhereParcel re-checks each parcel about every 12 hours for up to 10 days and posts the result after every check.

Should I poll or use webhooks?

Use a synchronous request when a person is waiting for an answer right now. Use webhooks for everything you track over time — order status emails, delivery dashboards, exception alerts. It’s cheaper and removes the scheduling code from your side.

Do I need a separate integration for each carrier?

Not with a unified API. One request format and one response format cover every live carrier; you pass a different carrier code. We explain why that matters in Multi-Carrier Tracking: Why You Need a Unified API.

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: #tracking-api #shipment-tracking #package-tracking #webhooks #guide #2026