Shipment Tracking API Reference — REST Endpoints
Real-time package & shipment tracking REST API. Single and bulk endpoints, auto carrier detection, code examples in cURL/Node/Python/PHP/Go. Cancel anytime.
Overview
Track up to 5 parcels at once. Supports 39+ carriers including USPS, UPS, FedEx, DHL, and more.
Some carriers are limited to 1 item per request:
The carriers listed below take substantially longer to look up, so a single synchronous request may contain at most 1 item across all of them combined — mixing two of them in one request is rejected as well. You can still batch them with other carriers: 1 item from this list + up to 4 items from any other carrier = 5 items total.
us.usps, us.fedex, us.ups, intl.dhl
This list may change. Exceeding the limit returns INVALID_REQUEST, and the error message names the exact carriers that triggered it. To track several items from these carriers, use /v2/webhooks/register (up to 100 items, asynchronous).
Events without a time: some carriers give only a date for certain events and no scan time (USPS does this for "In Transit to Next Facility" and "Pre-Shipment"). In that case timestamp is filled with noon on that date to stay valid ISO 8601, and the event carries timeUnknown: true. When the field is absent, the time came from the carrier and is real.
When to use this endpoint:
Use /v2/track for on-demand, one-off lookups — for example, when a customer checks their order status on your website.
For continuous monitoring, use Webhooks instead.
If you need to keep your database in sync with delivery status (e.g., updating order records, triggering notifications), register a webhook subscription via /v2/webhooks/register with recurring: true. The webhook approach is far more efficient — instead of polling repeatedly, you receive a push notification only when the status actually changes.
Rate Limits:
Each API key has per-minute and per-month request quotas based on your plan. When exceeded, the API returns HTTP 429. See response headers X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Reset-Minute (and the -Day / -Month variants) for current usage.
| Plan | Requests/min | Requests/month |
|---|---|---|
| Starter | 30 | 10,000 |
| Pro | 60 | 30,000 |
| Business | 200 | 300,000 |
Example Request
// npm install whereparcel
import { WhereParcel } from 'whereparcel';
const wp = new WhereParcel('YOUR_API_KEY', 'YOUR_SECRET_KEY');
const { data, summary } = await wp.track([
{
"carrier": "us.ups",
"trackingNumber": "1Z999AA10123456784"
},
{
"carrier": "us.ontrac",
"trackingNumber": "D10017048734180"
}
]);
console.log(summary);
for (const result of data) {
if (result.status === 'success') {
console.log(result.carrier, result.data.deliveryStatus);
}
} 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.ups",
"trackingNumber": "1Z999AA10123456784"
},
{
"carrier": "us.ontrac",
"trackingNumber": "D10017048734180"
}
]
}' const response = await fetch('https://api.whereparcel.com/v2/track', {
method: 'POST',
headers: {
"Authorization": "Bearer YOUR_API_KEY:YOUR_SECRET_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
"trackingItems": [
{
"carrier": "us.ups",
"trackingNumber": "1Z999AA10123456784"
},
{
"carrier": "us.ontrac",
"trackingNumber": "D10017048734180"
}
]
})
});
const data = await response.json();
console.log(data); <?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/track');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
$headers = [
'Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
'Content-Type: application/json'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$data = [
'trackingItems' => [
[
'carrier' => "us.ups",
'trackingNumber' => "1Z999AA10123456784"
],
[
'carrier' => "us.ontrac",
'trackingNumber' => "D10017048734180"
]
]
];
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
print_r($result); import requests
url = 'https://api.whereparcel.com/v2/track'
headers = {
'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
'Content-Type': 'application/json'
}
data = {
'trackingItems': [
{
'carrier': "us.ups",
'trackingNumber': "1Z999AA10123456784"
},
{
'carrier': "us.ontrac",
'trackingNumber': "D10017048734180"
}
]
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result) package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.whereparcel.com/v2/track"
payload := []byte(`{"trackingItems":[{"carrier":"us.ups","trackingNumber":"1Z999AA10123456784"},{"carrier":"us.ontrac","trackingNumber":"D10017048734180"}]}`)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
req.Header.Add("Authorization", "Bearer YOUR_API_KEY:YOUR_SECRET_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
} Replace the test API key with your actual API key from the dashboard.
Request Body
trackingItems array · required | |
trackingItems[].carrier string · required | Carrier code (e.g., 'us.usps', 'us.fedex', 'de.gls') |
trackingItems[].trackingNumber string · required | Tracking number |
trackingItems[].clientId string | Client tracking ID (returned as-is in the response) |
trackingItems[].postalCode string | Postal code (required/optional for some carriers, e.g., GLS Germany) |
trackingItems[].phoneNumber string | Phone number (required/optional for some carriers) |
Response
Success Response (200)
{
"success": true,
"data": [
{
"carrier": "us.fedex",
"trackingNumber": "231300687629630",
"clientId": "order-123",
"status": "success",
"billable": true,
"cached": false,
"data": {
"deliveryStatus": "delivered",
"events": [
{
"timestamp": "2026-02-04T18:00:00-05:00",
"status": "in_transit",
"location": "Newark, NJ",
"description": "At local FedEx facility"
},
{
"timestamp": "2026-02-05T09:15:00-05:00",
"status": "out_for_delivery",
"location": "Brooklyn, NY",
"description": "On FedEx vehicle for delivery"
},
{
"timestamp": "2026-02-05T14:30:00-05:00",
"status": "delivered",
"location": "New York, NY",
"description": "Delivered, left at front door"
}
],
"from": {
"name": "J. Smith"
},
"to": {
"name": "M. Johnson"
},
"lastUpdated": "2026-02-05T14:30:00-05:00"
}
},
{
"carrier": "us.usps",
"trackingNumber": "9400111899223197428490",
"status": "success",
"billable": true,
"cached": false,
"data": {
"deliveryStatus": "in_transit",
"events": [
{
"timestamp": "2026-02-05T12:00:00-05:00",
"status": "in_transit",
"location": "Chicago, IL",
"description": "In transit to next facility"
}
],
"lastUpdated": "2026-02-05T12:00:00-05:00"
}
}
],
"summary": {
"total": 2,
"success": 2,
"failed": 0,
"usageIncremented": 2
},
"requestLimit": {
"second": "1/10"
},
"trackingQuota": {
"minute": "2/30",
"day": "2/10000",
"month": "152/10000"
}
} Error Response (400)
{
"success": false,
"error": {
"code": "REQUEST_VALIDATION_FAILED",
"message": "1 invalid item(s) found"
}
} Error Response (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} Error Response (403)
{
"success": false,
"error": {
"code": "DEMO_KEY_BROWSER_ONLY",
"message": "This test key only works from the WhereParcel Playground (https://whereparcel.com/playground)."
}
} Error Response (429)
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Please try again later."
}
} Overview
Returns the carriers whose tracking-number format matches the input, most specific first (specificityScore). Pattern matching only — no carrier lookup and no usage counted.
Pick the candidate with the highest specificityScore, then call /v2/track with that carrier code. confirmed is present only when exactly one carrier matches.
Example Request
// npm install whereparcel
import { WhereParcel } from 'whereparcel';
const wp = new WhereParcel('YOUR_API_KEY', 'YOUR_SECRET_KEY');
const detected = await wp.detect('1Z999AA10123456784');
if (detected.confirmed) {
console.log('carrier:', detected.confirmed);
} else if (!detected.noMatch) {
console.log('candidates:', detected.candidates.map((c) => c.code));
} curl -X POST https://api.whereparcel.com/v2/detect \
-H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"trackingNumber": "1Z999AA10123456784"
}' const response = await fetch('https://api.whereparcel.com/v2/detect', {
method: 'POST',
headers: {
"Authorization": "Bearer YOUR_API_KEY:YOUR_SECRET_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
"trackingNumber": "1Z999AA10123456784"
})
});
const data = await response.json();
console.log(data); <?php $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/detect'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST'); $headers = [ 'Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY', 'Content-Type: application/json' ]; curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $data = [ 'trackingNumber' => "1Z999AA10123456784" ]; curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data)); $response = curl_exec($ch); curl_close($ch); $result = json_decode($response, true); print_r($result);
import requests
url = 'https://api.whereparcel.com/v2/detect'
headers = {
'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
'Content-Type': 'application/json'
}
data = {
'trackingNumber': "1Z999AA10123456784"
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result) package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.whereparcel.com/v2/detect"
payload := []byte(`{"trackingNumber":"1Z999AA10123456784"}`)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
req.Header.Add("Authorization", "Bearer YOUR_API_KEY:YOUR_SECRET_KEY")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
} Replace the test API key with your actual API key from the dashboard.
Request Body
trackingNumber string · required | The tracking number to check (up to 100 characters; spaces, dashes and dots are ignored) |
Response
Success Response (200)
{
"success": true,
"data": {
"input": "1Z999AA10123456784",
"normalized": "1Z999AA10123456784",
"candidates": [
{
"code": "us.ups",
"name": "UPS (United Parcel Service)",
"country": "US",
"pattern": {
"regex": "^(1Z[A-Z0-9]{16}|T[0-9]{10}|[0-9]{9,34})$",
"description": "1Z + 16 alphanumeric characters (incl. check digit), T + 10 digits, or 9-34 digits (Mail Innovations/SurePost)",
"examples": [
"1ZW4420K0310663099",
"9216490395160105988026"
]
},
"specificityScore": 67,
"formatName": "UPS",
"serviceTypes": [
"UPS United States Next Day Air (Red)"
]
},
{
"code": "intl.dhl",
"name": "DHL Express",
"country": "INTL",
"pattern": {
"regex": "^([0-9]{10,39}|[A-Z]{2}[0-9]{9}[A-Z]{2}|JD[0-9]{18,22})$",
"description": "10-39 digits, international postal format (2 letters + 9 digits + 2 letters), or JD + digits",
"examples": [
"1234567890",
"AB123456789CD"
]
},
"specificityScore": 20,
"formatName": "DHL Express",
"serviceTypes": []
},
{
"code": "ca.loomis",
"name": "Loomis Express",
"country": "CA",
"pattern": {
"regex": "^[A-Z0-9]{10,30}$",
"description": "Alphanumeric 10-30 characters (e.g., LSHP46411066, LQJ0Z3N0AALSHP46411066)",
"examples": [
"LSHP46411066",
"LQJ0Z3N0AALSHP46411066"
]
},
"specificityScore": 2
},
{
"code": "ca.ics",
"name": "ICS Courier",
"country": "CA",
"pattern": {
"regex": "^[A-Z0-9]{15,25}$",
"description": "Alphanumeric 15-25 characters (e.g., ND6C2BV3HBB0BEJ9Z1E2)",
"examples": [
"ND6C2BV3HBB0BEJ9Z1E2"
]
},
"specificityScore": 2
},
{
"code": "intl.cainiao",
"name": "Cainiao",
"country": "INTL",
"pattern": {
"regex": "^(LP[A-Z0-9]{14,20}|[A-Z]{2}[0-9]{9}[A-Z]{2}|CAINIAO[A-Z0-9]+|[A-Z0-9]{10,30})$",
"description": "LP + 14-20 characters, international postal format, CAINIAO prefix, or 10-30 alphanumeric characters",
"examples": [
"LP00123456789012345",
"AB123456789CD"
]
},
"specificityScore": 2
}
],
"format": "1Z + 16 alphanumeric characters (incl. check digit), T + 10 digits, or 9-34 digits (Mail Innovations/SurePost)",
"noMatch": false
}
} Error Response (400)
{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "Field \"trackingNumber\" (string) is required in request body."
}
} Error Response (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
}