Sandbox & Testing

Overview

The FreightCake sandbox provides a complete mock environment for developing and testing your integration without making real carrier API calls or incurring charges.

Use a test-mode API key (fk_test_...) to access sandbox mode. All data created with test keys is isolated from production data.

Mock Carrier Behavior

The sandbox includes a mock carrier ("Sandbox Freight Co") that returns deterministic responses based on your input:

Standard Quotes

Most requests return 3 quotes with realistic pricing:

Service	Base Rate	Transit
Standard LTL	~$0.35/lb	3-5 days
Guaranteed	~$0.50/lb	2-3 days
Economy	~$0.25/lb	5-7 days

Special Scenarios

Control sandbox behavior using specific input values:

Input	Behavior
Destination zip `00000`	Returns zero quotes (no coverage)
Destination zip `99999`	Simulates carrier timeout error
Reference containing `EXCEPTION`	Triggers delivery exception in tracking

Tracking Simulation

Sandbox shipments include full tracking history with events progressing through: Picked Up → In Transit → Out for Delivery → Delivered

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

{
  "object": "sandbox.reset",
  "reset": true,
  "organization_id": 1
}

Sandbox Status

Check sandbox health and data counts:

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

{
  "object": "sandbox.status",
  "organization_id": 1,
  "livemode": false,
  "data_counts": {
    "quotes": 12,
    "shipments": 3,
    "tracked_shipments": 2,
    "invoices": 1
  }
}

Simulate Events

Trigger webhook events for testing your event handlers:

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

Available events:

shipment.in_transit
shipment.out_for_delivery
shipment.delivered
shipment.exception
shipment.cancelled
invoice.created
invoice.overdue

Best Practices

Start with test keys — develop your entire integration in sandbox mode first
Test error scenarios — use zip code 99999 to test timeout handling
Test empty results — use zip code 00000 to test "no quotes" UI
Verify webhooks — use /sandbox/simulate and /webhook_endpoints/:id/test to confirm your webhook handlers work
Reset before demos — use /sandbox/reset to clear test data before demonstrations
Switch to live keys last — only change to fk_live_ keys when you're ready for production

On this page