Quickstart: Node.js

Ship your first label in under 5 minutes with TypeScript.

Quickstart: Node.js

From zero to a shipping label in 5 minutes.

Step 1: Get your API key

1. Create a free account at packageretriever.com
2. Open Apps & Tools → Unleashed tab
3. Click Create Key → choose Sandbox → copy the key

Step 2: Install the SDK

npm install @packageretriever/sdk

Step 3: Validate an address

Your first API call — costs nothing, succeeds immediately.

import PackageRetriever from '@packageretriever/sdk';

const pr = new PackageRetriever('pr_test_YOUR_KEY_HERE');

const validated = await pr.addresses.validate({
  name: 'Jane Smith',
  street1: '417 Montgomery St',
  city: 'San Francisco',
  state: 'CA',
  zip: '94104',
  country: 'US'
});

console.log(validated.valid);                      // true
console.log(validated.delivery_type);              // 'commercial'
console.log(validated.residential_surcharge_applies); // false

Step 4: Get rates

const rates = await pr.rates.get({
  from_address: {
    name: 'Warehouse',
    street1: '417 Montgomery St',
    city: 'San Francisco',
    state: 'CA',
    zip: '94105',
    country: 'US'
  },
  to_address: {
    name: 'Customer',
    street1: '123 Main St',
    city: 'Austin',
    state: 'TX',
    zip: '78701',
    country: 'US'
  },
  parcel: {
    weight_oz: 16,
    length: 9,
    width: 6,
    height: 2
  }
});

// Sorted cheapest first
console.log(rates.rates[0]);
// {
//   carrier: 'USPS',
//   service: 'Ground Advantage',
//   rate_cents: 542,
//   carrier_eta: '2026-05-20',
//   carbon_grams: 142
// }

Step 5: Buy a label

const label = await pr.labels.create({
  rate_id: rates.rates[0].id
});

console.log(label.tracking_number); // 9999... (sandbox)
console.log(label.label_url);       // Sample PDF URL
console.log(label.rate_cents);      // 542

Step 6: You’re done

Next steps:

• Set up webhooks to get notified when labels are created
• Connect your carrier accounts to use your negotiated rates
• Go to production — swap your test key for a live key

Full working example

import PackageRetriever from '@packageretriever/sdk';

const pr = new PackageRetriever(process.env.PR_API_KEY!);

async function shipOrder(order: { address: any; weight_oz: number }) {
  // 1. Get rates
  const rates = await pr.rates.get({
    from_address: { name: 'My Store', street1: '417 Montgomery St', city: 'San Francisco', state: 'CA', zip: '94105', country: 'US' },
    to_address: order.address,
    parcel: { weight_oz: order.weight_oz }
  });

  if (rates.rates.length === 0) {
    throw new Error('No rates available');
  }

  // 2. Buy cheapest label
  const label = await pr.labels.create({
    rate_id: rates.rates[0].id
  });

  return {
    tracking: label.tracking_number,
    labelPdf: label.label_url,
    cost: label.rate_cents
  };
}