Building a Shipping SDK in Node.js: Practical Patterns

If you're building a Node.js application that generates shipping labels, you need a clean abstraction over multiple carrier APIs. Here's how to structure a shipping SDK that doesn't become unmaintainable.

The Carrier Adapter Pattern

Every carrier (USPS, FedEx, UPS) has a different API — different auth, different request formats, different error codes. Wrap each in an adapter with a unified interface:

Define a common interface with methods like getRates(shipment), createLabel(shipment, service), trackPackage(trackingNumber), and cancelLabel(labelId). Then implement a separate adapter for each carrier that translates between your unified format and the carrier's API format.

HTTP Client Setup

Use axios or got with proper defaults:

• Timeout: 30 seconds for label generation, 10 seconds for tracking
• Retries: 3 retries with exponential backoff for 5xx errors only
• Keep-alive: Enable HTTP keep-alive — carriers like FedEx have slow TLS handshakes
• Logging: Log request/response for debugging (redact API keys)

Handling Carrier Errors

Each carrier returns errors differently. Normalize them:

Map carrier-specific error codes to your own standardized codes. This lets your frontend handle errors consistently regardless of which carrier was used.

Rate Shopping Implementation

The most common operation: get rates from multiple carriers and find the cheapest. Make parallel requests to all enabled carriers, collect the results, and sort by price:

Key points:

• Use Promise.allSettled, not Promise.all — one carrier being down shouldn't prevent others from returning rates
• Set a strict timeout (5 seconds) — if a carrier is slow, skip it
• Cache results for 15 minutes — rates don't change that frequently

Environment Configuration

Structure your carrier config by environment:

• Development: Use carrier sandbox/test APIs (USPS test endpoint, FedEx sandbox)
• Staging: Use carrier sandbox with production-like data
• Production: Real carrier APIs with real credentials

Never put carrier API keys in code. Use environment variables or a secrets manager. Load config at startup and validate that all required keys are present before accepting any requests.

Testing Without Carrier APIs

Mock carrier responses in tests using recorded fixtures. Make a real API call once, save the response, and replay it in tests. This gives you realistic test data without hitting rate limits or incurring charges.

Get started with Atoship's Node.js SDK →