v1.0.0

Package Tracking API

Track UPS, FedEx, USPS, DHL packages via simple REST API. Subscription-based with intelligent caching.

Base URL

https://justinvutrackingapi.site

Authentication

Every request requires an API key. Two key types available:

User API Key jv_live_xxx

For direct tool/script integration

Authorization: Bearer jv_live_your_key

OpenClaw Key oc_live_xxx

For OpenClaw instance integration

X-OpenClaw-Key: oc_live_your_key

Endpoints

Track Packages

POST
POST /api/track/batch
RuleValue
Min tracking numbers5
Max tracking numbers10

Request Body

{
  "trackingNumbers": [
    "9302027530832808100498",
    "9302055107210304061793",
    "9302001201042507529402",
    "9302070658154203378472",
    "9400109206094487929276"
  ]
}

Example

curl -X POST https://justinvutrackingapi.site/api/track/batch \
  -H "Authorization: Bearer jv_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumbers": [
      "9302027530832808100498",
      "9302055107210304061793",
      "9302001201042507529402",
      "9302070658154203378472",
      "9400109206094487929276"
    ]
  }'

Response

{
  "success": true,
  "total": 5,
  "successCount": 4,
  "errorCount": 1,
  "usage": {
    "used": 28,
    "limit": 3000,
    "month": "2026-03",
    "newTracks": 2,
    "cachedTracks": 3
  },
  "data": [
    {
      "TrackingNumber": "9302027530832808100498",
      "Carrier": "USPS",
      "Status": "In Transit",
      "Delivered": false,
      "_cached": false,
      "TrackingDetails": [...]
    },
    ...
  ]
}

Check Usage

GET
GET /api/usage
curl -H "Authorization: Bearer jv_live_your_key" \
  https://justinvutrackingapi.site/api/usage

Response

{
  "userId": "user123",
  "name": "John Doe",
  "plan": "monthly",
  "subscription": {
    "status": "active",
    "endDate": "2026-04-28T00:00:00.000Z",
    "isExpired": false
  },
  "monthlyUsage": {
    "month": "2026-03",
    "used": 28,
    "limit": 3000,
    "remaining": 2972,
    "percentage": 1
  }
}

Health Check

GET
GET /api/health  // No auth required

Usage & Pricing

Monthly Quota

Unique tracks/month3,000
Per request5 - 10 numbers
Reset1st of each month

What Counts vs Free

New tracking numberCounts (1 quota)
Already cached numberFREE
Call same number 100xStill FREE
Caching explained: Once a tracking number is fetched, it is cached in our database. Any future request for the same number returns cached data instantly — no quota charged. Delivered/returned packages are cached permanently.

Subscription Plans

PlanDurationMonthly Quota
Trial7 days3,000 tracks
Monthly30 days3,000 tracks
Yearly365 days3,000 tracks/month
Lifetime100 years3,000 tracks/month

Supported Carriers

UPSUnited Parcel Service
FedExFederal Express
USPSUnited States Postal Service
DHLDHL Express
Auto-detectCarrier from tracking number
Real-timeLive tracking updates
HistoryFull tracking timeline

Error Codes

CodeDescription
400Bad Request — Invalid parameters or less than 5 tracking numbers
401Unauthorized — Invalid, missing, or expired API key
429Limit Exceeded — Monthly quota used up or subscription expired
500Server Error — Internal error