Sandbox / Testing

Use test mode to build and verify your integration without dispatching real drivers or incurring charges. Test mode is activated by using an API key with the zx_test_ prefix.

Recommended test sequence

Start by requesting a quote, create a delivery with test data, confirm status progression, then validate webhook delivery and signature verification before switching to a live key.

How test mode works

All endpoints behave identically to live mode, but no real-world actions are taken.
Deliveries are assigned to a simulated driver and auto-advance through statuses.
Quotes return realistic fees and ETAs based on actual distance calculations.
Webhooks fire with test payloads to your registered endpoints.
Rate limits are the same as live mode (100 requests per minute).
Test and live data are completely separate -- a delivery created with a test key is not visible with a live key, and vice versa.

Simulated delivery lifecycle

In test mode, deliveries automatically progress through each status on a timer. This lets you test your webhook handlers and status-change logic without waiting.

created(10s)↓
pending(5s)↓
driver_assigned(15s)↓
picked_up(20s)↓
in_transit(30s)↓
delivered

Status	Duration	Notes
created	10 seconds	Initial state after creation.
pending	5 seconds	Simulated driver matching.
driver_assigned	15 seconds	Test driver assigned. Driver details become available.
picked_up	20 seconds	Package collected from pickup location.
in_transit	30 seconds	Simulated driver location updates along the route.
delivered	Terminal	Delivery complete.

Total time from creation to delivery: approximately 80 seconds.

Test driver details

All test deliveries are assigned to the same simulated driver:

Field	Value
Name	Test Driver
Phone	+10000000000
Location	Interpolated along the route between pickup and dropoff

Test webhooks

Webhooks registered with a test key fire for test-mode events. The payloads are identical in structure to live payloads, so your handler code works in both modes.

You can distinguish test events from live events by checking the delivery ID prefix or the API key used to register the webhook.

Webhook endpoint: local or hosted

For local development, use a tool like ngrok to expose your server. If your app is already deployed (e.g. on Firebase Hosting, Vercel, or another host), register your hosted webhook URL (e.g. https://your-app.com/webhooks/zippex) with a test key so sandbox events are delivered to the same endpoint you use in production.

"color:#6a9955"># Start your local server
node server.js  "color:#6a9955"># listening on port 3000

"color:#6a9955"># In a separate terminal, expose it
ngrok http 3000

"color:#6a9955"># Register the ngrok URL as your webhook
curl -X POST https:"color:#6a9955">//api.zippex.com/v1/webhooks \
  -H "Authorization: Bearer zx_test_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://a1b2c3.ngrok.io/webhooks/zippex",
    "events": ["*"]
  }'

Switching to live

When you are ready to go live, replace your test API key with your live key:

"color:#6a9955"># .env
"color:#6a9955"># Test mode
"color:#6a9955"># ZIPPEX_API_KEY=zx_test_abc123def456

"color:#6a9955"># Live mode
ZIPPEX_API_KEY=zx_live_xyz789ghi012

No code changes are needed -- the API behavior is identical. The only difference is that live keys dispatch real drivers and charge real fees.

Related guides

Authentication for key handling and environment separation
Tracking for polling behavior and public tracking URLs
Webhooks for event delivery and signature verification