shipstation-node


Unofficial ShipStation API wrapper for Node.js, providing a modern, type-safe interface to both the v1 and v2 ShipStation APIs.

---

Features

- Full support for both ShipStation v1 and v2 APIs
- Complete TypeScript support and request validation with detailed type definitions
- Automatic rate limiting handling
- Mock API support for testing (only available for v2 API)
- Promise-based async/await interface
- Customizable request configurations with automatic retries

---

Installation

$3

Using npm:

``bash
$ npm install shipstation-node
`

Using pnpm:

`bash
$ pnpm add shipstation-node
`

Using bun:

`bash
$ bun add shipstation-node
`

---

Usage

$3

All requests should be made through an instantiated ShipStation class. You only need to set the credentials for the API version(s) you plan to use.

`ts
import ShipStation from 'shipstation-node';

// Create instance
const shipstation = new ShipStation({
credentials: {
// For making v1 API calls
v1: { apiKey, apiSecret },
// For making v2 API calls
v2: { apiKey }
}
});
`

$3

You can make API requests to both v1 and v2 endpoints:

`ts
// v1 Example - List Tags (https://www.shipstation.com/docs/api/accounts/list-tags/)
const tags = await shipstation.v1.accounts.listTags();

// v2 Example: Get Tags (https://docs.shipstation.com/openapi/tags/list_tags)
const tagsV2 = await shipstation.v2.tags.get();

// Working with orders (https://www.shipstation.com/docs/api/orders/list-orders/)
const orders = await shipstation.v1.orders.list({
pageSize: 100,
orderStatus: 'awaiting_shipment'
});
`

$3

Use the mock API for testing (v2 API only):

`ts
const shipstation = new ShipStation({
credentials: { v2: { mock: true } }
});
`

---

Advanced Configuration

$3

Configure automatic retry behavior for failed API calls using axios-retry:

`ts
const shipstation = new ShipStation({
credentials: {
/ ... /
},
retryConfig: {
retries: 3,
retryDelay: (retryCount) => retryCount * 1000,
retryCondition: (error) => {
return axios.isRetryableError(error);
}
}
});
`

$3

Customize the underlying axios request settings:

`ts
const shipstation = new ShipStation({
credentials: {
/ ... /
},
requestConfig: {
timeout: 5000,
headers: {
'Custom-Header': 'value'
}
}
});
`

---

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a new branch (git checkout -b feature-name)
3. Commit your changes (git commit -m 'Add feature')
4. Test your changes (pnpm run build and pnpm run lint)
5. Push to the branch (git push origin feature-name`)
6. Open a pull request with a thorough description

---

Links

- v1 API Documentation
- v2 API Documentation
- Changelog
- Issues
- GitHub Repository

---

Support

If you encounter any issues, feel free to open an issue.

---

License

This project is licensed under the MIT License.

---

Author

Created and maintained by Jake Leventhal.