SDKs / Node.js

Node.js SDK

The official Node.js client for the Serian ShipKit API. Ships with full TypeScript types, automatic retries, and idempotency support.

Installation

bash

npm install @serianshipkit/sdk

Requires Node 18 or later.

Quick start

typescript

import { SerianLogistics } from "@serianshipkit/sdk";

const sl = new SerianLogistics({
  apiKey: process.env.SERIAN_API_KEY!,
});

// 1. Get rates
const rates = await sl.rates.list({
  shipper: {
    name: "Accra Warehouse",
    street1: "12 Independence Ave",
    city: "Accra",
    state: "GA",
    zip: "00233",
    country: "GH",
  },
  recipient: {
    name: "Kwame Mensah",
    street1: "45 Oxford St",
    city: "London",
    state: "LND",
    zip: "W1D 2DZ",
    country: "GB",
  },
  parcels: [
    { length: 30, width: 20, height: 15, weight: 2.5,
      dimension_unit: "CM", weight_unit: "KG" },
  ],
});

console.log(rates); // Rate[]

// 2. Create a shipment with the cheapest rate
const shipment = await sl.shipments.create({
  rate_id: rates[0].rate_id,
  reference: "ORDER-1234",
});

console.log(shipment.tracking_number);

Configuration

Option	Type	Default	Description
`apiKey`	`string`	—	Your API key (`sk_live_` or `sk_test_`)
`baseUrl`	`string`	`https://api.serianshipkit.com`	Override the API base URL
`retries`	`number`	`2`	Number of automatic retries on 5xx / network errors

API reference

Rates

Method	HTTP	Description
`sl.rates.list(input)`	`POST /rates`	Get shipping rates for a parcel

Shipments

Method	HTTP	Description
`sl.shipments.create(input, idempotencyKey?)`	`POST /shipments`	Create a shipment and generate a label
`sl.shipments.get(id)`	`GET /shipments/:id`	Retrieve a shipment by ID
`sl.shipments.list({ limit?, status? })`	`GET /shipments`	List shipments with optional filters
`sl.shipments.cancel(id)`	`DELETE /shipments/:id`	Cancel a shipment

Tracking

Method	HTTP	Description
`sl.tracking.get(tracking_number, carrier?)`	`GET /tracking`	Get tracking events for a shipment

Webhooks

Method	HTTP	Description
`sl.webhooks.list()`	`GET /webhooks`	List registered webhook endpoints
`sl.webhooks.register(url, events)`	`POST /webhooks`	Register a new webhook endpoint

Error handling

Every API error throws a SerianLogisticsError with structured metadata you can use for logging or retry logic.

typescript

import { SerianLogistics, SerianLogisticsError } from "@serianshipkit/sdk";

const sl = new SerianLogistics({ apiKey: process.env.SERIAN_API_KEY! });

try {
  await sl.shipments.get("ship_nonexistent");
} catch (err) {
  if (err instanceof SerianLogisticsError) {
    console.error(err.status);    // 404
    console.error(err.code);      // "shipment_not_found"
    console.error(err.requestId); // "req_abc123"
    console.error(err.details);   // additional context (if any)
  }
}

Test mode

Use an API key prefixed with sk_test_ to hit the sandbox environment. Test-mode shipments never reach a carrier and labels are watermarked. Switch to sk_live_when you’re ready for production.

Exported types

The package re-exports the following TypeScript types for convenience:

typescript

import type {
  Rate,
  Shipment,
  TrackingResponse,
  WebhookEndpoint,
} from "@serianshipkit/sdk";

For full endpoint documentation, see the API Reference.