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.
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
IMpb with ZIP (IMpd)34 digits
420 10023 3424 9200 1901 3260 7600 8334 57
Legacy20 digits
7112 3456 7891 2345 6787
International (UPU S10)13 characters
EE 123 456 785 US
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) | deliveryStatus | Note |
|---|---|---|
| "Shipping Label Created, USPS Awaiting Item" | pending | |
| "Accepted at USPS Origin Facility" | in_transit | |
| "Picked up by Shipping Partner" | in_transit | A partner took it to deliver — not delivered yet. |
| "Out for Delivery" | out_for_delivery | |
| "Notice Left" | in_transit | An 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 |
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')) {
"success": true,
"data": [{
"carrier": "us.usps",
"status": "success",
"data": {
"deliveryStatus": "in_transit",
"events": [ … ]
},
"billable": true
}]
} - APer item:
successorerror— one bad number doesn't fail the batch. - BOne of nine values; USPS's wording is in
rawStatuson each event (FIG. 2). - 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.
Related Resources
- 5-minute API setup guide — first request to webhook in cURL/Node/Python/Go
- Best parcel tracking API 2026 — 5-way comparison — WhereParcel vs AfterShip, 17TRACK, Tracktry, Parcellab
- Understanding tracking number formats by carrier — every major carrier's regex with examples
- Building a branded tracking page — Shopify, WooCommerce, custom
- Webhook best practices — signature verification, retries, idempotency
- Browse all 39+ live carriers
Start tracking USPS packages in minutes.
Read the Docs Open Playground