We’re excited to announce the release of whereparcel — the official Node.js SDK for the WhereParcel package tracking API.

npm install whereparcel

Why an SDK?

While our REST API works great with any HTTP client, we wanted to make the developer experience even smoother. The SDK gives you:

  • Type-safe responses — Full TypeScript definitions for every API response
  • Zero dependencies — Uses native fetch (Node.js 18+), no bloated dependency tree
  • Simpler auth — Pass your API key once, never think about headers again
  • Error handling built-in — Typed error classes like AuthenticationError and RateLimitError

Quick Start

import { WhereParcel } from 'whereparcel';

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

// Track a single parcel
const response = await wp.track([
  { carrier: 'us.usps', trackingNumber: '9400111899562537866361' },
]);

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

That’s it. No manual header construction, no JSON parsing, no URL building.

Bulk Tracking

Need to track multiple parcels at once? The SDK supports up to 5 items per request:

const response = await wp.track([
  { 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 }

Carrier Discovery

Explore our 500+ supported carriers programmatically:

// All carriers
const carriers = await wp.getCarriers();

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

// Filter by region
const caCarriers = await wp.getCarriersByRegion('us', 'ca');

Webhook Support

Set up real-time delivery notifications:

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

// Register tracking with recurring monitoring
await wp.registerWebhook({
  trackingItems: [{ carrier: 'us.usps', trackingNumber: '...' }],
  recurring: true,
  webhookEndpointId: endpoint.endpointId,
});

Error Handling

The SDK provides typed error classes so you can handle failures gracefully:

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

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

What’s Next

This is version 0.1.0 — a solid foundation. Here’s what we’re working on:

  • Python SDK — Coming soon for Python developers
  • Webhook signature verification — Helper to verify webhook payloads
  • Retry logic — Automatic retry with exponential backoff

Get Started

Install the SDK and start tracking in minutes:

npm install whereparcel

We’d love to hear your feedback. If you run into any issues or have feature requests, reach out through our community page.