Documentation
Everything you need to integrate the rateship SDK into your Node backend.
Everything you need to integrate the rateship SDK into your Node backend.
rateship is a provider-agnostic Node SDK for shipping rates, labels, and webhooks across EasyPost, Shippo, and ShipEngine. One typed API, zero runtime dependencies, MIT-licensed.
Requires Node 20+. Dual CJS + ESM build, full TypeScript types.
npm install rateship
You bring your own credentials. No rateship account required. See Provider Setup for dashboard links and key formats. At least one provider is required; configure all three for maximum carrier coverage.
Each provider is wired up with a factory function. Pass whichever ones you have keys for to the RateShip constructor.
import { RateShip, easypost, shippo, shipengine } from "rateship";
const client = new RateShip({
providers: [
easypost({ apiKey: process.env.EASYPOST_KEY! }),
shippo({ apiKey: process.env.SHIPPO_KEY! }),
shipengine({ apiKey: process.env.SHIPENGINE_KEY! }),
],
});getRates() fans out to every configured provider in parallel and returns normalized rates sorted by price. Per-provider failures land in errors[] instead of throwing. One provider being down never kills the call.
const { rates, errors } = await client.getRates({
from: {
name: "Warehouse",
street1: "500 Terry A Francois Blvd",
city: "San Francisco",
state: "CA",
zip: "94158",
country: "US",
},
to: {
name: "Jane Doe",
street1: "1600 Amphitheatre Pkwy",
city: "Mountain View",
state: "CA",
zip: "94043",
country: "US",
},
parcel: {
weight: 2,
weight_unit: "lb",
length: 10,
width: 8,
height: 6,
distance_unit: "in",
},
});
// rates: NormalizedRate[] (sorted ascending by price_cents)
// errors: ProviderError[] (one entry per failed provider, empty when all OK)Pass any rate back to createLabel. The SDK uses the provider-native identifiers on the rate to buy through the correct adapter in a single API call.
const label = await client.createLabel(rates[0]); console.log(label.tracking_number); // "1Z..." console.log(label.label_url); // https://... (PDF download) console.log(label.label_id); // provider-native label identifier
The current release is optimized for US domestic shipping:country: "US"on addresses, weight_unit: "lb" | "oz", rates filtered to USD. International support lands in v2.1+ as an additive widening, so v2.0 code won't break when it ships.
rateship is a provider-agnostic Node SDK for shipping rates, labels, and webhooks across EasyPost, Shippo, and ShipEngine. One typed API, zero runtime dependencies, MIT-licensed.
Requires Node 20+. Dual CJS + ESM build, full TypeScript types.
npm install rateship
You bring your own credentials. No rateship account required. See Provider Setup for dashboard links and key formats. At least one provider is required; configure all three for maximum carrier coverage.
Each provider is wired up with a factory function. Pass whichever ones you have keys for to the RateShip constructor.
import { RateShip, easypost, shippo, shipengine } from "rateship";
const client = new RateShip({
providers: [
easypost({ apiKey: process.env.EASYPOST_KEY! }),
shippo({ apiKey: process.env.SHIPPO_KEY! }),
shipengine({ apiKey: process.env.SHIPENGINE_KEY! }),
],
});getRates() fans out to every configured provider in parallel and returns normalized rates sorted by price. Per-provider failures land in errors[] instead of throwing. One provider being down never kills the call.
const { rates, errors } = await client.getRates({
from: {
name: "Warehouse",
street1: "500 Terry A Francois Blvd",
city: "San Francisco",
state: "CA",
zip: "94158",
country: "US",
},
to: {
name: "Jane Doe",
street1: "1600 Amphitheatre Pkwy",
city: "Mountain View",
state: "CA",
zip: "94043",
country: "US",
},
parcel: {
weight: 2,
weight_unit: "lb",
length: 10,
width: 8,
height: 6,
distance_unit: "in",
},
});
// rates: NormalizedRate[] (sorted ascending by price_cents)
// errors: ProviderError[] (one entry per failed provider, empty when all OK)Pass any rate back to createLabel. The SDK uses the provider-native identifiers on the rate to buy through the correct adapter in a single API call.
const label = await client.createLabel(rates[0]); console.log(label.tracking_number); // "1Z..." console.log(label.label_url); // https://... (PDF download) console.log(label.label_id); // provider-native label identifier
The current release is optimized for US domestic shipping:country: "US"on addresses, weight_unit: "lb" | "oz", rates filtered to USD. International support lands in v2.1+ as an additive widening, so v2.0 code won't break when it ships.