# WhereParcel — Full Documentation for LLMs

> Unified parcel tracking API for 43+ carriers across 11 countries. Track USPS, UPS, FedEx, DHL, CJ Logistics, Yamato, and more with a single REST API.

## Overview

WhereParcel provides a single API endpoint to track packages from 43+ carriers worldwide. Instead of building separate integrations for each carrier, developers use one unified API with normalized JSON responses, real-time webhook notifications, and bulk tracking support.

- Website: https://whereparcel.com
- API Base URL: https://api.whereparcel.com
- OpenAPI Spec: https://whereparcel.com/openapi.en.yaml
- Pricing model: paid plans start with payment — no free trial. Cancel anytime (access until the end of the billing period). Instant no-signup testing: public demo key on the playground, 20 requests/day per IP
- Ambassador program: publish a post about WhereParcel and earn 3+ months of your plan free (quality-based) — https://whereparcel.com/ambassador

## Free Spreadsheet Tools (No Coding Required)

WhereParcel provides free tools for non-developers to track parcels in bulk from spreadsheets.

### Excel VBA Macro (Windows)

Download the macro-enabled workbook (.xlsm) and track parcels directly from Microsoft Excel.

**Setup:**
1. Download: https://whereparcel.com/downloads/WhereParcel_Tracker.xlsm
2. Open the file and click "Enable Content"
3. Press Alt+F8, run `SetupAll` — creates Settings, Tracking, Carrier Codes, Instructions sheets
4. Enter API Key and Secret Key in the Settings sheet (demo keys pre-filled for testing)

**Usage:**
1. Enter carrier codes (column B) and tracking numbers (column C) in the Tracking sheet
2. Click "Register Tracking"
3. Wait 5-10 seconds
4. Click "Fetch Results"

VBA source only: https://whereparcel.com/downloads/TrackingMacro.bas (import via Alt+F11)

### Google Apps Script (Mac, Windows, Chromebook)

Same features as Excel, runs in Google Sheets via Apps Script. No installation required.

**Option 1 — Use template (easiest):**
Copy the pre-built template: https://docs.google.com/spreadsheets/d/13OQEGzTlFHzG8xj31ldPYq6L0IQPozgSc_eWfdTP64g/copy
Then click WhereParcel > Setup All.

**Option 2 — Add to existing spreadsheet:**
1. Extensions > Apps Script
2. Paste contents of https://whereparcel.com/downloads/Code.gs
3. Save and refresh — "WhereParcel" menu appears
4. Click WhereParcel > Setup All

**Menu items:** Register Tracking, Fetch Results, Clear Results, Setup All

### Spreadsheet Tool Features

- **Batch processing:** Up to 100 items per batch, auto-split for larger sets
- **43+ carriers across 11 countries:** UPS, USPS, FedEx, DHL, CJ Logistics, Yamato, Royal Mail, and more
- **Smart carrier input:** Type "ups" → `us.ups`, "fedex" → `us.fedex`, "yamato" → `jp.yamato`, "롯데택배" → `kr.lotte`
- **Color-coded status:** Green = Delivered, Blue = In Transit, Orange = Pending, Red = Failed
- **Untracked Only mode:** Skip rows that already have results (saves API usage)
- **Auto-update:** Check and apply macro updates without re-downloading

**Tool page:** https://whereparcel.com/tools/spreadsheet-tracker
**Blog — Excel guide:** https://whereparcel.com/blog/excel-tracking-macro-free-download
**Blog — Google Sheets guide:** https://whereparcel.com/blog/google-sheets-parcel-tracking

The spreadsheet tools use the same webhook API under the hood (POST /v2/webhooks/register + GET /v2/webhooks/subscriptions/{requestId}).

---

## Authentication

All API requests require authentication via Bearer token:

```
Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY
Content-Type: application/json
```

Get your keys at https://whereparcel.com/dashboard/api-keys (free signup).

## Tracking API

### POST /v2/track

Track one or more parcels. Supports up to 5 items per request.

**Request:**
```json
{
  "trackingItems": [
    {
      "carrier": "us.usps",
      "trackingNumber": "9400111899223033005282"
    }
  ]
}
```

**Response:**
```json
{
  "results": [
    {
      "carrier": "us.usps",
      "trackingNumber": "9400111899223033005282",
      "status": "IN_TRANSIT",
      "deliveryStatus": {
        "code": "IN_TRANSIT",
        "label": "In Transit"
      },
      "events": [
        {
          "time": "2026-02-11T08:30:00Z",
          "status": "IN_TRANSIT",
          "description": "In Transit to Next Facility",
          "location": "DISTRIBUTION CENTER, CA"
        }
      ],
      "estimatedDelivery": "2026-02-13T18:00:00Z",
      "carrier": {
        "code": "us.usps",
        "name": "USPS",
        "country": "US"
      }
    }
  ]
}
```

**Carrier code format:** `{country}.{carrier}` — e.g., `us.usps`, `kr.cjlogistics`, `jp.yamato`, `gb.royalmail`

### Batch tracking

Send multiple items in a single request:
```json
{
  "trackingItems": [
    { "carrier": "us.usps", "trackingNumber": "9400111899223033005282" },
    { "carrier": "kr.cjlogistics", "trackingNumber": "123456789012" },
    { "carrier": "jp.yamato", "trackingNumber": "1234-5678-9012" }
  ]
}
```

## Carriers API

### GET /v2/carriers

List all supported carriers. Free endpoint (no usage count).

### GET /v2/countries

List all supported countries. Free endpoint.

### GET /v2/carriers/{countryCode}

Filter carriers by country (ISO 3166-1 alpha-2 code).

Example: `GET /v2/carriers/US` returns all US carriers (USPS, UPS, FedEx, etc.)

## Webhooks API

### POST /v2/webhooks/register

Subscribe to tracking updates. When a parcel's status changes, WhereParcel sends a POST to your webhook URL.

**Request:**
```json
{
  "webhookEndpointId": "ep_abc123",
  "recurring": true,
  "trackingItems": [
    { "carrier": "us.usps", "trackingNumber": "9400111899223033005282" }
  ]
}
```

- `recurring: true` — continuous monitoring (polling) until delivered
- `recurring: false` — single lookup, results sent once

### GET /v2/webhooks/subscriptions

List your active webhook subscriptions.

### POST /v2/webhook-endpoints

Register a webhook receiver URL.

**Request:**
```json
{
  "url": "https://yoursite.com/webhooks/tracking",
  "description": "Production tracking updates"
}
```

## Code Examples

### cURL
```bash
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":"9400111899223033005282"}]}'
```

### Node.js
```javascript
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.usps', trackingNumber: '9400111899223033005282' }],
  }),
});
const data = await response.json();
```

### Python
```python
import requests

response = requests.post(
    'https://api.whereparcel.com/v2/track',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'trackingItems': [{'carrier': 'us.usps', 'trackingNumber': '9400111899223033005282'}]
    },
)
data = response.json()
```

## Pricing

Paid plans start with payment — there is no free trial. Cancel anytime; you keep access until the end of the billing period. Ambassador program: publish a post about WhereParcel and earn 3+ months free (quality-based).

| Plan | Requests/month | Price | Key Features |
|------|---------------|-------|-------------|
| Starter | 10,000 | $49/mo | Webhooks, email support |
| Pro | 30,000 | $99/mo | Priority support, advanced analytics |
| Growth | 100,000 | $250/mo | Priority support |
| Scale | 200,000 | $450/mo | Dedicated support |
| Business | 300,000 | $650/mo | Dedicated support, 99.95% SLA |

All plans include access to all 43+ carriers.

## Supported Countries and Carriers

### South Korea (KR) — 7 carriers
Korea Post, CJ Logistics, Lotte Global Logistics, Hanjin Express, Logen, Daesin, KD Express.

### United States (US) — 5 carriers
USPS, UPS, FedEx, OnTrac, OnTrac (California).

### Japan (JP) — 2 carriers
Yamato Transport, Japan Post.

### Germany (DE) — 4 carriers
Hermes Germany, GLS Germany, Deutsche Post, FedEx Germany.

### United Kingdom (GB) — 3 carriers
Royal Mail, Evri, FedEx UK.

### International (INTL) — 8 carriers
DHL Express, TNT Express, Chronopost International, Cainiao, Yanwen, YunExpress, Canada Post International, Deutsche Post International.

### Other countries
Canada (6), Italy (3), Spain (2), Turkey (2), Australia (1).

## FAQ

**Q: How do I get started?**
A: Sign up at https://whereparcel.com/signup for free. Get your API key from the dashboard and make your first tracking request in under 5 minutes.

**Q: What carrier code format do you use?**
A: Carrier codes follow the format `{country}.{carrier}` — for example, `us.usps`, `kr.cjlogistics`, `jp.yamato`. Use GET /v2/carriers to see all codes.

**Q: Can I track packages from multiple carriers in one request?**
A: Yes. Send up to 5 items with different carriers in a single POST /v2/track request.

**Q: How do webhooks work?**
A: Register a webhook endpoint URL, then subscribe tracking items. When a parcel's status changes, WhereParcel sends a POST request to your URL with the updated tracking data.

**Q: What's the response time?**
A: Cached results return in under 500ms. Live lookups typically complete in 2-3 seconds.

**Q: Is there a rate limit?**
A: Yes, rate limits depend on your plan. Free: 1 req/min, 5/month. Starter: 30/min, 10K/month. Pro: 60/min, 30K/month. Business: 200/min, 300K/month.

**Q: Do you support auto-detection of carriers?**
A: Currently, you must specify the carrier code. Auto-detection by tracking number format is planned.

## Links

- Homepage: https://whereparcel.com
- Documentation: https://whereparcel.com/docs
- API Reference: https://whereparcel.com/docs/api/tracking
- Carriers List: https://whereparcel.com/carriers
- Playground: https://whereparcel.com/playground
- Sign Up: https://whereparcel.com/signup
- Community: https://whereparcel.com/community
- OpenAPI Spec (EN): https://whereparcel.com/openapi.en.yaml
- OpenAPI Spec (KO): https://whereparcel.com/openapi.ko.yaml
- OpenAPI Spec (JA): https://whereparcel.com/openapi.ja.yaml