Documentation

Everything you need to integrate the rateship SDK into your Node backend.

Provider Setup

The SDK talks to EasyPost, Shippo, and ShipEngine directly from your backend using API keys you provide. No rateship account, no key storage. Below: where to get each key and any provider-specific gotchas.

EasyPost

Dashboard: easypost.com/account/api-keys
Key format: EZ_... (test) or EZAK_... (production)
Auth: HTTP Basic with the key as username, password empty.

Shippo

Dashboard: apps.goshippo.com/settings/api
Key format: shippo_test_... or shippo_live_...
Auth header: Authorization: ShippoToken <key>
Carrier activation: each carrier (UPS, USPS, FedEx, etc.) has to be activated separately under Shippo's Carriers settings. A fresh test account may return zero rates until you click Activate Account on the carriers you care about.

ShipEngine

Dashboard: app.shipengine.com/#/settings/api-keys
Key format: TEST_... (test) or live_... (production)
Auth header: API-Key: <key>
ShipStation keys also work with the SDK, ShipStation uses ShipEngine's API under the hood.

Wiring them up

Factory functions, one per provider, return adapters that plug into the RateShip constructor. Missing apiKey throws CONFIGURATION_ERROR immediately; construction does not hit the network, so invalid keys surface on the first getRates() call via errors[].

import { RateShip, easypost, shippo, shipengine } from "rateship";

// Configure any subset. At least one provider is required.
const client = new RateShip({
  providers: [
    easypost({ apiKey: process.env.EASYPOST_KEY! }),
    shippo({ apiKey: process.env.SHIPPO_KEY! }),
    shipengine({ apiKey: process.env.SHIPENGINE_KEY! }),
  ],
});

Tree-shaking

If you only use one provider, import its factory via the subpath to keep the bundle smaller:

import { RateShip } from "rateship";
import { easypost } from "rateship/providers/easypost";

const client = new RateShip({ providers: [easypost({ apiKey: "..." })] });

Subpath entries: rateship/providers/easypost, rateship/providers/shippo, rateship/providers/shipengine.

One per type

At v2.0 you can configure at most one adapter per provider type. Passing two easypost(...) adapters with different keys throws CONFIGURATION_ERROR at construction. Multi-tenant key rotation lands in a later release.

Next: Getting Rates.