Sandbox & Testing

Overview

Use a test-mode API key (fk_test_...) to keep quotes, freight, tracking records, invoices, and webhook events separate from live-mode data. Test and live keys use the same API origin and endpoint paths.

Carrier availability and responses depend on the test integrations configured for your organization. Do not build tests around undocumented ZIP codes or fixed prices.

Sandbox Routes

These endpoints are only available with test-mode keys:

Reset Sandbox Data

Delete all test-mode data for your organization:

curl -X POST https://api.freightcake.com/api/v1/sandbox/reset \
  -H "Authorization: Bearer fk_test_REPLACE_WITH_YOUR_KEY"

{
  "object": "sandbox.reset",
  "status": "ok"
}

Sandbox Status

Check sandbox health and data counts:

curl https://api.freightcake.com/api/v1/sandbox/status \
  -H "Authorization: Bearer fk_test_REPLACE_WITH_YOUR_KEY"

{
  "object": "sandbox.status",
  "shipments": 3,
  "quotes": 12,
  "bols": 3,
  "invoices": 1
}

Simulate Events

Trigger webhook events for testing your event handlers:

curl -X POST https://api.freightcake.com/api/v1/sandbox/simulate/shipment.delivered \
  -H "Authorization: Bearer fk_test_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipment_id": 1
  }'

You can simulate any supported webhook event type. FreightCake adds simulated: true to the event data and merges the JSON request body into it.

Best Practices

Start with test keys — develop your entire integration in sandbox mode first
Verify webhooks — use /sandbox/simulate/:event_type and /webhooks/:id/test to confirm your handlers
Reset before demos — use /sandbox/reset to clear test-mode transactional data
Switch to live keys last — create a fk_live_ key only when you are ready for production operations