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

Package manager

Using npm:

$ npm install shipstation-node

Using pnpm:

$ pnpm add shipstation-node

Using bun:

$ bun add shipstation-node

Usage

Create a Client Instance

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.

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

Making API Requests

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

// 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'
});

Mock API Support

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

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

Advanced Configuration

Retry Configuration

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

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

Request Configuration

Customize the underlying axios request settings:

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.