SDKs

ShipStation provides official SDKs for the ShipStation API V2. Each SDK's client is generated from the same OpenAPI specification that powers this documentation, and it is regenerated automatically whenever the API changes. As a result, the SDK's methods and types stay in sync with the API reference.

npm install @shipstation/shipstation-js-sdk

Requires Node.js >=22. The package ships as both ESM and CommonJS.

import { ShipStationAPI } from '@shipstation/shipstation-js-sdk';

const api = new ShipStationAPI('your-api-key');

const shipments = await api.shipments.listShipments();

Every resource in the API is exposed as a property on the ShipStationAPI instance (for example api.shipments, api.labels, api.rates), matching the tags in the API reference.

You can pass a configuration object instead of an API key:

const api = new ShipStationAPI({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.shipstation.com', // default
  timeout: 60000, // per-attempt request timeout, in ms
  fetch: customFetch, // override the fetch implementation (testing, proxies, HTTP/2, ...)
  middleware: [myMiddleware], // extra middleware appended after the SDK's own
});

Every operation is available in two forms, for example listCarriers and listCarriersRaw:

// Plain: returns the parsed response body
const carriers = await api.carriers.listCarriers();

// Raw: gives access to the HTTP status and headers
const raw = await api.carriers.listCarriersRaw();
raw.raw.status;
const body = await raw.value();

Use the plain method by default, and the Raw variant only when you need the status code or headers.

All errors thrown by the SDK extend ShipStationError:

• ShipStationApiError: the API responded with a non-2xx status. It includes status, errors (the parsed error body), and requestId when the API returned one.
• ShipStationConnectionError: the request failed before a response was received (network error, DNS, etc.).
• ShipStationTimeoutError: the request exceeded the configured timeout.

import { ShipStationApiError } from '@shipstation/shipstation-js-sdk';

try {
  await api.labels.createLabel({ createLabelRequest: { /* ... */ } });
} catch (error) {
  if (error instanceof ShipStationApiError) {
    console.error(error.status, error.errors, error.requestId);
  }
}

The SDK follows semantic versioning. Two changelogs are maintained in the repository:

• CHANGELOG.md: SDK package releases.

To report a bug or request a feature, open an issue in the repository.