# Sandbox Environment

A sandbox environment allows you to test API functionality without incurring real costs or affecting production data. You can create test shipments, purchase test labels, and experiment with API features in a safe, isolated environment.

## Availability

ShipStation API Customers Only
The sandbox environment is **only available to ShipStation API customers (formerly ShipEngine)**. It is **not available** to ShipStation platform (web UI) users.

If you use the ShipStation platform, all V2 API operations occur in production and may incur real costs. See [Testing with Production Keys](#testing-without-sandbox-shipstation-platform-customers) below for best practices.

### ShipStation API Customers (formerly ShipEngine)

If you're a ShipStation API customer (formerly ShipEngine), you have access to sandbox environments on all plan levels:

- **Sandbox keys** are prefixed with `TEST_`
- Use the same `TEST_` keys with V2 endpoints at `https://api.shipstation.com/v2/`
- All sandbox operations are free and don't affect production data
- Sandbox and production environments are completely isolated


### ShipStation Platform Customers

If you use the ShipStation platform (web UI):

- **No sandbox environment is available**
- All V2 API operations occur in production
- Creating labels, purchasing shipping, and other operations may incur real costs
- See the section below for testing strategies


## Using the Sandbox (ShipStation API Customers)

### Getting Your Sandbox API Key

1. Log in to your [ShipStation API dashboard](https://api-portal.shipstation.com/)
2. Navigate to your API keys section
3. Generate or copy your sandbox API key (prefixed with `TEST_`)
4. Use this key in the `API-Key` header when making requests to V2 endpoints


### Making Sandbox Requests

Use your `TEST_` prefixed API key with V2 endpoints at `https://api.shipstation.com/v2/`:


```http
POST /v2/labels HTTP/1.1
Host: api.shipstation.com
API-Key: TEST_your_sandbox_key_here
Content-Type: application/json

{
  "shipment": {
    "carrier_id": "se-123456",
    "service_code": "usps_priority_mail",
    ...
  }
}
```

### Sandbox Capabilities

In the sandbox environment, you can:

- **Create test shipments** without real shipping costs
- **Purchase test labels** that won't be charged
- **Test carrier integrations** without connecting real accounts
- **Validate address data** without consuming production quotas
- **Test webhooks** by subscribing to sandbox events
- **Experiment with API features** safely


### Sandbox Limitations

The sandbox environment has some limitations:

- **Test labels cannot be used for actual shipping** - they're for testing only
- **Carrier-specific features** may behave differently in sandbox vs. production
- **Rate quotes** in sandbox may not reflect current production rates
- **Tracking updates** are simulated, not from real carriers
- **Data doesn't persist indefinitely** - sandbox data may be periodically cleared


### Switching Between Environments

To switch between sandbox and production:

**Sandbox:**


```http
API-Key: TEST_your_sandbox_key_here
```

**Production:**


```http
API-Key: your_production_key_here
```

That's it! The same V2 endpoints (`https://api.shipstation.com/v2/`) work with both keys.

## Testing Without Sandbox (ShipStation Platform Customers)

If you're a ShipStation platform customer and don't have access to sandbox, here are recommended testing strategies:

### Best Practices for Production Testing

1. **Use low-cost shipping options** for test labels
  - Choose the cheapest available service for your test shipments
  - Use lightweight packages to minimize costs
2. **Void test labels immediately**
  - Use the [void label endpoint](/void-labels) right after creation
  - Most carriers refund voided labels if voided quickly
3. **Start with small volumes**
  - Test with 1-5 labels initially
  - Scale up only after confirming your integration works correctly
4. **Consider carrier billing timing**
  - Some carriers bill on label creation (e.g., USPS)
  - Others bill on carrier scan-in (e.g., UPS, FedEx)
  - For initial testing, consider carriers that bill on scan and simply don't tender the packages
5. **Request a developer account**
  - Contact ShipStation support to request a developer account
  - Developer accounts have an extended trial period (90 days)
  - Still operates in production, but gives you more time for testing
  - You must connect your own carriers and test stores


### Testing Address Validation

Address validation can be tested without creating labels:

- Use the `validate_address` parameter with [POST /v2/shipments](/shipments/create)
- Use the `validate_address` parameter with [POST /v2/rates](/rate-shopping)
- Use the direct [address validation endpoint](/validate-addresses) (ShipStation API customers only)


### Testing Rate Shopping

Rate shopping doesn't incur costs:

- Use [POST /v2/rates](/rate-shopping) to compare carrier rates
- No charges for getting rate quotes
- Test your rate selection logic without purchasing labels


## Sandbox vs. Production Comparison

| Feature | Sandbox (ShipStation API only) | Production |
|  --- | --- | --- |
| **Availability** | ShipStation API customers only | All customers |
| **Cost** | Free | Real costs may apply |
| **Labels** | Test labels only | Real, usable labels |
| **Tracking** | Simulated | Real carrier tracking |
| **Carrier accounts** | Test accounts | Real carrier accounts required |
| **Data persistence** | Temporary | Permanent |
| **API endpoints** | `https://api.shipstation.com/v2/` | `https://api.shipstation.com/v2/` |
| **API key prefix** | `TEST_` | No prefix |


## Additional Resources

- [Security & Authentication](/authentication) - Learn about API keys and authentication
- [Getting Started](/getting-started) - Get started with ShipStation V2 API
- [ShipStation API Sandbox (ShipEngine docs)](/apis/shipengine/docs/getting-started/sandbox) - Detailed ShipEngine sandbox documentation