Test safely in the sandbox

The sandbox (the practice server) uses the same login, estimate and order calls as production, but the order lifecycle is simulated. No real riders accept or deliver orders. Use your own login email and key there.

Its address is shown on the Developers page of the outlet portal under Try it safely first, and in the box that opens when you create your key.

Close

How the simulation works#

1. Create an order with POST /api/orders on the sandbox. It is saved as CREATED with real distance and pricing from your outlet settings.

2. Optionally pass scenario_type. It is sandbox-only. If you leave it out, the default is full_flow.

3. A background runner advances the order every 30 seconds: it assigns a dummy delivery executive, updates the status, writes timeline events and fires your sandbox webhook, if you set one.

4. Poll GET /api/orders/:id or listen for webhooks to watch the changes.

Scenario types#

Pass scenario_type when you create the order. Production ignores this field.

Example. Set SANDBOX_URL to the practice server address:

curl -X POST "$SANDBOX_URL/api/orders" \  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "drop_latitude": 12.9716,    "drop_longitude": 77.5946,    "customer_name": "Customer Name",    "customer_phone": "+919876543210",    "scenario_type": "full_flow"  }'

Webhooks in the sandbox#

Set a Sandbox webhook URL (optional) and a Sandbox webhook secret (optional) on the Developers page. Use the same receiver logic as for production and treat the production payload as the contract. In the sandbox, track_url points at a static demo page.

Riders and trips in the sandbox#

• Riders (/api/delivery-executives): stored in the sandbox’s own database. No email is sent and riders cannot log in. Every rider is work_online: true with location_fresh: true, and app_download_url is null. Routes, fields and error codes match production.

• Trips: POST /api/trips and GET /api/trips/:tripId work with a stand-in optimiser. All queued orders go to one dummy rider in creation order and are always assigned.

• The sandbox does not support Idempotency-Key, auto_assign=false, the approve endpoint or the list endpoint.