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.

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

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

1. Log in to your ShipStation API dashboard
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

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

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",
    ...
  }
}

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

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

To switch between sandbox and production:

Sandbox:

API-Key: TEST_your_sandbox_key_here

Production:

API-Key: your_production_key_here

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

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

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

Address validation can be tested without creating labels:

• Use the validate_address parameter with POST /v2/shipments
• Use the validate_address parameter with POST /v2/rates
• Use the direct address validation endpoint (ShipStation API customers only)

Rate shopping doesn't incur costs:

• Use POST /v2/rates to compare carrier rates
• No charges for getting rate quotes
• Test your rate selection logic without purchasing labels

• Security & Authentication - Learn about API keys and authentication
• Getting Started - Get started with ShipStation V2 API
• ShipStation API Sandbox (ShipEngine docs) - Detailed ShipEngine sandbox documentation