WhereParcel

Official Node.js SDK for the WhereParcel package tracking API. Track parcels across 500+ carriers worldwide including USPS, FedEx, UPS, DHL, and more.

Install

npm install whereparcel

Quick Start

import { WhereParcel } from 'whereparcel';

const wp = new WhereParcel('your-api-key', 'your-secret-key');

const result = await wp.track('us.usps', '9400111899562537866361');

if (result.status === 'success') {
  console.log(result.data.deliveryStatus); // 'delivered'
  console.log(result.data.events);         // Tracking events
}

Get your API key at whereparcel.com/dashboard.

Features

• 500+ carriers — USPS, FedEx, UPS, DHL, and carriers across 50+ countries
• TypeScript first — Full type definitions included
• Zero dependencies — Uses native fetch (Node.js 18+)
• Bulk tracking — Track up to 50 parcels per request
• Webhooks — Real-time delivery notifications
• ESM + CJS — Works with both module systems

API Reference

Constructor

const wp = new WhereParcel(apiKey, secretKey, options?);

| Parameter | Type | Description | |-----------|------|-------------| | apiKey | string | Your API key | | secretKey | string | Your secret key | | options.baseUrl | string | API base URL (default: https://api.whereparcel.com) | | options.timeout | number | Request timeout in ms (default: 30000) |

Tracking

track(carrier, trackingNumber, clientId?)

Track a single parcel.

const result = await wp.track('us.fedex', '123456789012');

if (result.status === 'success') {
  console.log(result.data.deliveryStatus);  // 'in_transit'
  console.log(result.data.estimatedDelivery); // '2026-03-01'
  console.log(result.data.events);          // Array of tracking events
}

if (result.status === 'error') {
  console.log(result.error.code);    // 'TRACKING_NOT_FOUND'
  console.log(result.error.message);
}

trackBulk(items)

Track multiple parcels in one request (max 50).

const response = await wp.trackBulk([
  { carrier: 'us.usps', trackingNumber: '9400111899562537866361' },
  { carrier: 'us.fedex', trackingNumber: '123456789012' },
  { carrier: 'kr.cj', trackingNumber: '1234567890', clientId: 'order-42' },
]);

console.log(response.summary);
// { total: 3, success: 2, failed: 1, usageIncremented: 2 }

for (const result of response.results) {
  if (result.status === 'success') {
    console.log(`${result.carrier}: ${result.data.deliveryStatus}`);
  }
}

Carriers

getCarriers()

List all supported carrier codes.

const carriers = await wp.getCarriers();
// ['kr.cj', 'kr.hanjin', 'us.fedex', 'us.ups', 'us.usps', ...]

getCountries()

List all supported country codes.

const countries = await wp.getCountries();
// ['kr', 'us', 'jp', 'cn', 'de']

getCarriersByCountry(country)

List carriers for a specific country.

const usCarriers = await wp.getCarriersByCountry('us');
// ['us.fedex', 'us.ups', 'us.usps', ...]

getCarriersByRegion(country, region)

List carriers for a specific region.

const caCarriers = await wp.getCarriersByRegion('us', 'ca');
// ['us.ca.ontrac', ...]

Webhooks

registerWebhook(options)

Register webhook tracking for parcels.

// One-time fetch
const result = await wp.registerWebhook({
  trackingItems: [{ carrier: 'us.usps', trackingNumber: '...' }],
});

// Recurring monitoring until delivery
const subscription = await wp.registerWebhook({
  trackingItems: [{ carrier: 'us.usps', trackingNumber: '...' }],
  recurring: true,
  webhookEndpointId: 'endpoint_abc123',
});

getSubscriptions()

List all active webhook subscriptions.

const subscriptions = await wp.getSubscriptions();

Webhook Endpoints

createWebhookEndpoint(options)

Create a URL endpoint to receive webhook events.

const endpoint = await wp.createWebhookEndpoint({
  name: 'Production',
  url: 'https://myapp.com/webhooks/whereparcel',
});

console.log(endpoint.endpointId); // 'endpoint_abc123'
console.log(endpoint.secret);     // 'whsec_...' — use to verify signatures

getWebhookEndpoints()

List all registered webhook endpoints.

const endpoints = await wp.getWebhookEndpoints();

Error Handling

import { WhereParcel, AuthenticationError, RateLimitError } from 'whereparcel';

try {
  const result = await wp.track('us.usps', '...');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API credentials');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  }
}

| Error Class | Status Code | When | |-------------|-------------|------| | AuthenticationError | 401 | Invalid or missing API key | | RateLimitError | 429 | Too many requests | | NotFoundError | 404 | Carrier or country not found | | WhereParcelError | Other | All other API errors |

Tracking Statuses

All carrier statuses are normalized to these values:

| Status | Description | |--------|-------------| | pending | Label created, not yet picked up | | in_transit | Package is in transit | | out_for_delivery | Out for delivery | | delivered | Successfully delivered | | failed | Delivery attempt failed | | returned | Returned to sender | | cancelled | Shipment cancelled | | unknown | Status could not be determined |

Requirements

• Node.js 18+ (uses native fetch)

Links

• Documentation
• API Playground
• Dashboard
• Carrier List

License

MIT