Sandbox

The sandbox is a safe practice environment. Use it while building and testing your integration.

Base URL: https://sandbox.developer.haulstow.co/v1
Key type: hsg_test_key_...

Sandbox and live data are completely separate. A recipient or delivery created in the sandbox does not exist in live mode. Sandbox responses make this visible:

{
  "environment": "test",
  "simulated": true,
  "tracking_url": null
}

What the sandbox does not do

It does not:

dispatch a real rider;
send SMS, email, or push notifications to a recipient;
charge or collect money;
create invoices or accounting entries;
reserve stock;
change a live order;
provide a live tracking link.

You can safely use example names, numbers, and addresses that meet validation rules. Avoid copying real customer data into a test environment unless you need it and are permitted to do so.

Deterministic quotes

Sandbox prices are fixed test values based on straight-line distance. They are designed to make tests predictable, not to forecast the exact price of a future live delivery.

Distance	Bike	Minivan
Up to 5 km	GHS 20	GHS 50
Over 5 km, up to 15 km	GHS 40	GHS 90
Over 15 km	Manual quote	Manual quote

A trip over 15 km returns:

{
  "fee": null,
  "requires_custom_quote": true
}

Simulate status changes

When you create a sandbox delivery, it starts at booked. In real life, riders and operations move the status forward. In the sandbox, call the transition helper yourself.

curl --request POST "$HAULSTOW_BASE_URL/test-helpers/deliveries/$HAULSTOW_DELIVERY_ID/transition" \
  --header "Authorization: Bearer $HAULSTOW_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-1842-assigned" \
  --data '{"status":"assigned"}'

The allowed order is:

booked -> assigned -> picked_up -> in_transit -> delivered
   |          |                         |
   +----------+-> cancelled             +-> failed

booked and assigned may also move to cancelled. in_transit may move to failed. Each call moves exactly one step. For example, these are invalid:

booked directly to delivered;
delivered back to in_transit;
any transition after a terminal state.

An invalid change returns 409 SANDBOX_TRANSITION_INVALID. Each accepted transition creates the same versioned event and signed webhook shape used in live mode. That makes the sandbox suitable for testing deduplication, ordering, signature verification, and terminal-state handling.

Moving to live mode

When your sandbox flow works:

Create a separate live key beginning with hsg_live_key_.
Change the base URL to https://developer.haulstow.co/v1.
Keep your request JSON and response parsing the same.
Remove any calls to /test-helpers/...; that route exists only on the sandbox host.
Start with a controlled real delivery and monitor its webhook or polling flow.

Never make your code automatically fall back from sandbox to live or from live to sandbox.

Get started

Core concepts

Endpoint reference

What the sandbox does not do

Deterministic quotes

Simulate status changes

Moving to live mode

​What the sandbox does not do

​Deterministic quotes

​Simulate status changes

​Moving to live mode

What the sandbox does not do

Deterministic quotes

Simulate status changes

Moving to live mode