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 -> assigned (retry)
   |          |
   +----------+-> outsourced -> delivered

Deliveries created with POST /deliveries/bulk also start at booked and use the same helper, one delivery at a time. booked and assigned may also move to cancelled or outsourced. in_transit may move to failed. A failed delivery may move back to assigned, which is how a live delivery is retried after a failed attempt. An outsourced delivery may move to delivered. 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.

Automatic simulation

Manual transitions are perfect for tests that must be exact and repeatable. They do not show you what a real delivery feels like: statuses changing on their own, webhooks arriving over several minutes, money collected at the door and paid out later. An automatic simulation does that for you. You pick a named scenario and the sandbox moves the delivery one step at a time, sending the same signed webhooks, in the same order, that a live delivery would send. Use it when you want to:

watch your webhook handler deal with a realistic stream of events;
try a case that is hard to set up by hand, such as a failed attempt that is retried;
demo your integration without clicking through every status yourself.

Keep using manual transitions for automated tests that need exact control over timing.

Start a simulation when you create the delivery

Add a sandbox object to POST /deliveries, or to any item of POST /deliveries/bulk:

curl --request POST "$HAULSTOW_BASE_URL/deliveries" \
  --header "Authorization: Bearer $HAULSTOW_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-1843-create" \
  --data '{
    "recipient_id": "rcp_3f1a821cdb58498cbb52f4706545a089",
    "recipient_address_id": "adr_78de60204f574a64be88ba9bd94a049f",
    "pickup": {
      "name": "Osu Store",
      "contact": "+233200000001",
      "address": "Oxford Street, Osu, Accra",
      "latitude": 5.556,
      "longitude": -0.182
    },
    "payment": { "type": "cod", "goods_value": 120 },
    "vehicle_type": "bike",
    "sandbox": { "scenario": "failed_then_retried", "step_delay_seconds": 5 }
  }'

scenario is required. Pick one from the table below.
step_delay_seconds is optional. It is the wait before each step, from 1 to 60 seconds. The default is 5.

sandbox works only with a test key. If a live key sends it, the request fails with 400 SANDBOX_ONLY_FIELD and nothing is created, so a test payload can never run against live by accident.

Start a simulation on an existing delivery

curl --request POST "$HAULSTOW_BASE_URL/test-helpers/deliveries/$HAULSTOW_DELIVERY_ID/simulate" \
  --header "Authorization: Bearer $HAULSTOW_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-1842-simulate" \
  --data '{"scenario":"failed_then_retried","step_delay_seconds":3}'

The response is 202 Accepted with the delivery. The scenario picks up from the delivery’s current status. For example, delivered on an in_transit delivery has just one step left. If the current status is not a point the scenario passes through, the call returns 409 SIMULATION_NOT_APPLICABLE.

Scenarios

Scenario	What happens	Works with
`delivered`	assigned, picked_up, in_transit, delivered	every payment type
`cod_settled`	everything in `delivered`, then the goods money is paid out (`delivery.settled`, `settlement.paid`)	`cod`
`cod_partial_collection`	assigned, picked_up, in_transit, delivered, then the rider collects only half of what is due	`cod`, or `delivery_only` with a delivery fee
`cancelled_before_assignment`	cancelled	every payment type
`cancelled_after_assignment`	assigned, cancelled	every payment type
`failed`	assigned, picked_up, in_transit, failed	every payment type
`failed_then_retried`	assigned, picked_up, in_transit, failed, then assigned, picked_up, in_transit, delivered	every payment type
`outsourced`	outsourced, delivered	every payment type

Whenever a delivery reaches delivered with money due at the door, delivery.payment_collected follows straight after delivery.delivered, exactly as it does with a manual transition. In cod_partial_collection the collection comes one step later and its collection.status is partially_collected, with amount_collected showing what the rider took. Every scenario uses only event sequences a live delivery can produce, so what you test here is what you will see in production.

Example timeline

Here is what your webhook endpoint receives for a COD delivery created with failed_then_retried and step_delay_seconds: 5:

Time	Event	`data.delivery.status`
10:15:00	`delivery.created`	`booked`
10:15:05	`delivery.assigned`	`assigned`
10:15:10	`delivery.picked_up`	`picked_up`
10:15:15	`delivery.in_transit`	`in_transit`
10:15:20	`delivery.failed`	`failed`
10:15:25	`delivery.assigned`	`assigned`
10:15:30	`delivery.picked_up`	`picked_up`
10:15:35	`delivery.in_transit`	`in_transit`
10:15:40	`delivery.delivered`	`delivered`
10:15:40	`delivery.payment_collected`	`delivered`

The sequence number keeps rising across the retry, so a handler that ignores older sequences works without changes. Times are approximate: a step can run up to about a second after it is due.

Watch progress

While a simulation exists, sandbox delivery responses include a simulation object. It is null on a sandbox delivery that never had one, and live deliveries do not have the field at all.

"simulation": {
  "scenario": "failed_then_retried",
  "status": "running",
  "step": 3,
  "steps_total": 8,
  "next_step_at": "2026-10-02T10:15:20Z"
}

status is one of:

running: steps are still being taken;
completed: every step ran;
stopped: you stopped it, the delivery was cancelled, or it ran for more than 24 hours;
failed: a step could not be applied, so the simulation ended where it was.

Stop a simulation

curl --request DELETE "$HAULSTOW_BASE_URL/test-helpers/deliveries/$HAULSTOW_DELIVERY_ID/simulation" \
  --header "Authorization: Bearer $HAULSTOW_API_KEY"

The delivery stays at whatever status it had reached. Calling it again is safe and returns the delivery unchanged.

Simulations and manual changes

While a simulation is running, the sandbox owns the delivery’s next steps:

POST /test-helpers/deliveries/{id}/transition and /settle return 409 SIMULATION_RUNNING. Stop the simulation first, then continue by hand.
A second simulate call on the same delivery also returns 409 SIMULATION_RUNNING.
POST /deliveries/{id}/cancel still works, because a real customer can cancel at any time before pickup. Cancelling stops the simulation.

Limits

One application can have up to 100 running simulations. Starting another returns 429 SIMULATION_LIMIT until some finish or you stop them.
A simulation that is still running 24 hours after it started is stopped automatically.

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

Automatic simulation

Start a simulation when you create the delivery

Start a simulation on an existing delivery

Scenarios

Example timeline

Watch progress

Stop a simulation

Simulations and manual changes

Limits

Moving to live mode

​What the sandbox does not do

​Deterministic quotes

​Simulate status changes

​Automatic simulation

​Start a simulation when you create the delivery

​Start a simulation on an existing delivery

​Scenarios

​Example timeline

​Watch progress

​Stop a simulation

​Simulations and manual changes

​Limits

​Moving to live mode

What the sandbox does not do

Deterministic quotes

Simulate status changes

Automatic simulation

Start a simulation when you create the delivery

Start a simulation on an existing delivery

Scenarios

Example timeline

Watch progress

Stop a simulation

Simulations and manual changes

Limits

Moving to live mode