whereparcel

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

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.

Try it in Playground Quick Start Guide → Get Started →

EndpointPOST/v2/track
Track parcels (billable)

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)

200OK — Successful tracking response
{
  "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)

400Bad Request — Invalid request — validation failed (REQUEST_VALIDATION_FAILED with invalidItems), more than one item from the limited carriers (INVALID_REQUEST), or demo-key item limit (DEMO_KEY_ITEM_LIMIT_EXCEEDED)
{
  "success": false,
  "error": {
    "code": "REQUEST_VALIDATION_FAILED",
    "message": "1 invalid item(s) found"
  }
}

Error Response (401)

401Unauthorized — Authentication failed - API key missing or invalid
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Error Response (403)

403Forbidden — Forbidden — the public demo key works only from the WhereParcel Playground (DEMO_KEY_BROWSER_ONLY), or the trial limit is reached (TRIAL_LIMIT_REACHED)
{
  "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)

429Too Many Requests — Rate limit or quota exceeded (RATE_LIMIT_EXCEEDED, MINUTE_QUOTA_EXCEEDED, MONTHLY_QUOTA_EXCEEDED, DEMO_KEY_IP_LIMIT_EXCEEDED)
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later."
  }
}
EndpointPOST/v2/detect
Detect carrier from tracking number (free)

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)

200OK — Carrier candidates
{
  "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)

400Bad Request — trackingNumber is missing, empty, or longer than 100 characters (INVALID_REQUEST)
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Field \"trackingNumber\" (string) is required in request body."
  }
}

Error Response (401)

401Unauthorized — Authentication failed - API key missing or invalid
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}