whereparcel

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

← United States Carriers

Carrier·United States·us.usps

USPS Tracking API

Track USPS packages with WhereParcel's unified tracking API. Support for Priority Mail, First-Class, Media Mail, and all USPS services. One API call, instant results.

Open Playground Read the Docs View Pricing

USPSSheet 1 of 1

Carrier Code
us.usps
Country
🇺🇸 United States
Status
Live
Number formats
4 — IMpb, IMpd, legacy, UPU S10 (FIG. 1)
Per request
1 tracking number (synchronous)
Response
The same JSON shape as all 39+ live carriers

USPS Tracking Number Formats

USPS prints four kinds of tracking numbers. us.usps accepts all four — the part that matters for routing is the first two digits, the service type code.

USPS Tracking (IMpb)22 digits

9400 1118 9956 2537 8663 61

94 94 = USPS Tracking 0011189956253786636 mailer ID + serial 1 check digit ✓

IMpb with ZIP (IMpd)34 digits

420 10023 3424 9200 1901 3260 7600 8334 57

420 420 = ZIP follows 100233424 ZIP+4 10023-3424 92 92 = Signature 0019013260760083345 mailer ID + serial 7 check ✓

Legacy20 digits

7112 3456 7891 2345 6787

71 71 = Certified Mail 12345678912345678 serial 7 check ✓

International (UPU S10)13 characters

EE 123 456 785 US

EE EE = EMS 12345678 serial 5 check (mod 11) ✓ US sent from the US
FIG. 1The four number families USPS issues, drawn to the digit. Every check digit above is computed, not illustrative.

What USPS says, what you get

USPS writes its scans in plain English. Each one maps to one of nine deliveryStatus values; USPS's own words stay in rawStatus.

rawStatus (USPS)deliveryStatusNote
"Shipping Label Created, USPS Awaiting Item"pending
"Accepted at USPS Origin Facility"in_transit
"Picked up by Shipping Partner"in_transitA partner took it to deliver — not delivered yet.
"Out for Delivery"out_for_delivery
"Notice Left"in_transitAn attempt isn't a failure — it can still be redelivered or picked up.
"Delivered, Front Door/Porch"delivered
"Undeliverable as Addressed"failed
"Return to Sender"returned
"Missing Mail Search Request Initiated"lost
FIG. 2Nine of the USPS scans we map, as USPS writes them. The two in blue are the ones a simple keyword match gets wrong.

Quick Start

Track USPS packages with a single API call:

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": "9400111899223456789017"
    }]
  }'
const response = await fetch('https://api.whereparcel.com/v2/track', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}:${SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    trackingItems: [{
      carrier: 'us.usps',
      trackingNumber: '9400111899223456789017',
    }],
  }),
});

const { data } = await response.json();
console.log(data[0].data?.deliveryStatus);
// → "in_transit", "delivered", etc.
import requests

response = requests.post(
    'https://api.whereparcel.com/v2/track',
    headers={
        'Authorization': f'Bearer {API_KEY}:{SECRET_KEY}',
        'Content-Type': 'application/json',
    },
    json={
        'trackingItems': [{
            'carrier': 'us.usps',
            'trackingNumber': '9400111899223456789017',
        }],
    },
)

item = response.json()['data'][0]
print(item.get('data', {}).get('deliveryStatus'))

200Response·abridged

{
  "success": true,
  "data": [{
    "carrier": "us.usps",
    "status": "success",
    "data": {
      "deliveryStatus": "in_transit",
      "events": [ … ]
    },
    "billable": true
  }]
}
  1. APer item: success or error — one bad number doesn't fail the batch.
  2. BOne of nine values; USPS's wording is in rawStatus on each event (FIG. 2).
  3. CCache hits come back with billable: false.

Automatic Updates with Webhooks

Instead of polling, register a webhook and we re-check your USPS parcels about every 12 hours, pushing each status to you. Each tracking number counts as just 1 request — no matter how many updates follow.

// Register a webhook endpoint
await fetch('https://api.whereparcel.com/v2/webhook-endpoints', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}:${SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Production',
    url: 'https://yourapp.com/webhooks/tracking',
    description: 'USPS tracking updates',
  }),
});

Why WhereParcel for USPS

  • Unified JSON — same response shape across USPS and the rest of our 39+ live carriers. No carrier-specific branching code.
  • Honest pricing — Starter $49/mo (10K req), Pro $99/mo (30K), Business $650/mo (300K). Cancel anytime.
  • Free 3 months — write one short blog post mentioning WhereParcel via the ambassador program and get 3 months of Starter free.
  • Don't see a carrier? — Request it on our community board — we add new carriers fast.

Try without signup

Use our free Tracking Number Validator to paste any USPS number and instantly see the carrier and service type — no account needed, runs entirely in your browser.

Try with sample USPS number →

Related Resources

Start tracking USPS packages in minutes.

Read the Docs Open Playground