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.

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": "9400111899223456789012"
    }]
  }'

USPS Tracking Number Formats

Service	Format	Example
Priority Mail	`9400 1118 9922 3XXX XXXX XX`	`9400111899223456789012`
First-Class Package	`9205 5XXX XXXX XXXX XXXX XX`	`9205590164917312345671`
Priority Mail International	`ECXX XXXX XXXX US`	`EC123456789US`

Code Examples

JavaScript / Node.js

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: '9400111899223456789012',
    }],
  }),
});

const data = await response.json();
console.log(data.trackingItems[0].status);
// → "in_transit", "delivered", etc.

Python

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': '9400111899223456789012',
        }],
    },
)

data = response.json()
print(data['trackingItems'][0]['status'])

Real-Time Updates with Webhooks

Instead of polling, register a webhook to receive USPS status updates automatically. Each tracking number counts as just 1 request — no matter how many status changes occur.

// 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({
    url: 'https://yourapp.com/webhooks/tracking',
    description: 'USPS tracking updates',
  }),
});