# SDKs

ShipStation provides official SDKs for the ShipStation API V2. Each SDK's client is generated from the same [OpenAPI specification](/apis/openapi) 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.

TIP
Get your API key before you start:

- **ShipStation API customers** (formerly ShipEngine): find yours in the [ShipStation API dashboard](https://api-portal.shipstation.com/).


## Available SDKs

| Language | Package | Repository |
|  --- | --- | --- |
| TypeScript / JavaScript | `@shipstation/shipstation-js-sdk` | [shipstation/shipstation-js-sdk](https://github.com/shipstation/shipstation-js-sdk) |


## TypeScript / JavaScript

### Installation


```bash
npm install @shipstation/shipstation-js-sdk
```

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

### Quickstart


```ts
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](/apis/openapi).

### Configuration

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


```ts
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
});
```

### Plain and raw methods

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


```ts
// 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.

### Error handling

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`.



```ts
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);
  }
}
```

### Versioning and changelogs

The SDK follows [semantic versioning](https://semver.org/). Two changelogs are maintained in the repository:

- [CHANGELOG.md](https://github.com/shipstation/shipstation-js-sdk/blob/main/CHANGELOG.md): SDK package releases.


To report a bug or request a feature, [open an issue](https://github.com/shipstation/shipstation-js-sdk/issues) in the repository.