> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ShipStation

> Integration details and setup guide for the ShipStation connector in Alloy Automation.

## Pre-Built Tooling

| Category                            | Details                                      |
| ----------------------------------- | -------------------------------------------- |
| **Authentication**                  | API Key (Basic Authentication)               |
| **Two-Way Sync**                    | No                                           |
| **Events Supported**                | Yes (via Webhooks)                           |
| **Realtime**                        | Yes (Webhooks)                               |
| **Supports Rate Limiting**          | Yes (40 requests per 60 seconds per API key) |
| **Authentication Scopes Supported** | N/A (API Key-based)                          |

***

## Objects Supported

Alloy Automation supports syncing the following objects from **ShipStation**:

* **Orders** - Order details and line items
* **Shipments** - Shipping labels and tracking
* **Products** - Product catalog
* **Warehouses** - Warehouse locations
* **Carriers** - Carrier accounts and services
* **Customers** - Customer information

***

## Set Up Guide

### Trial Access

| Question                                           | Answer                                                                                                                            |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Offers free trial?**                             | Yes. ShipStation offers a 30-day free trial with full access to features. [Start free trial](https://www.shipstation.com/signup/) |
| **Requires paid sandbox**                          | No. The trial environment can be used for development.                                                                            |
| **Requires partnership to obtain authentication?** | No. Anyone can create an account and obtain API credentials.                                                                      |

***

### Authentication (API Key)

ShipStation uses API Key and API Secret for Basic Authentication.

<step>
  ## Step 1: Create a ShipStation Account

  1. Visit **ShipStation** ([https://www.shipstation.com/](https://www.shipstation.com/))
  2. Click **Start Your Free Trial**
  3. Fill out the registration form
  4. Complete the onboarding process
  5. You'll get 30 days of free access to all features
</step>

<step>
  ## Step 2: Generate API Credentials

  1. Log into your ShipStation account
  2. Navigate to **Settings** (gear icon) > **API Settings**
  3. Under **API Keys**, click **Generate New API Keys**
  4. Provide a name for the key (e.g., "Alloy Integration")
  5. Copy the **API Key** and **API Secret**
  6. Store these credentials securely—you won't be able to view the secret again
</step>

<step>
  ## Step 3: Configure API Permissions

  1. API keys have full account access by default
  2. Review the permissions and ensure they meet your integration needs
  3. For production, consider creating separate API keys for different integrations
  4. Monitor API key usage in the API Settings page
</step>

<step>
  ## Step 4: Connect to Alloy Automation

  1. In Alloy Automation, configure your ShipStation connector
  2. Provide:
     * **API Key**: Your ShipStation API Key
     * **API Secret**: Your ShipStation API Secret
  3. ShipStation uses Basic Authentication with API Key as username and API Secret as password
  4. Test the connection by retrieving orders or warehouses
</step>

***

## Use Cases

### 1) Automated order import

Automatically import orders from e-commerce platforms into ShipStation, enabling centralized shipping label creation and fulfillment tracking across multiple sales channels.

### 2) Real-time shipment tracking

Sync shipment tracking numbers and carrier information from ShipStation back to e-commerce stores, customer support systems, or notification platforms for automated shipping updates.

### 3) Multi-warehouse fulfillment

Route orders to the optimal warehouse based on inventory availability, customer location, or shipping rules by integrating ShipStation with inventory management systems.

### 4) Carrier rate shopping

Retrieve real-time shipping rates from multiple carriers through ShipStation, enabling dynamic shipping cost calculation at checkout or in order management systems.

### 5) Returns management

Automate return label generation and returns processing by connecting ShipStation with customer support platforms, e-commerce stores, or returns management systems.

***

## API Gotchas

* **Rate Limiting:** ShipStation enforces a rate limit of 40 requests per 60 seconds (rolling window) per API key. Exceeding this limit results in 429 status codes. Implement exponential backoff and request queuing to stay within limits.

* **Order Status vs. Shipment Status:** ShipStation distinguishes between order status (awaiting\_shipment, shipped, cancelled) and shipment status (label created, shipped, delivered). Understanding this distinction is crucial for proper order lifecycle management.

* **Webhook Reliability:** ShipStation webhooks may occasionally fail or be delayed. Implement idempotency handling and consider polling critical endpoints as a backup to ensure no data is missed.

* **Pagination for Large Datasets:** ShipStation APIs return paginated results. Use `page` and `pageSize` parameters (max 500 items per page). Always check if there are more pages to fetch using the total count in responses.

* **Date Range Limitations:** When querying orders or shipments by date, ShipStation limits the date range to 90 days per request. For historical data imports, make multiple requests with smaller date ranges.

> For questions or troubleshooting, contact **[support@runalloy.com](mailto:support@runalloy.com)**.