10-minute quickstart

This walkthrough creates a delivery in the sandbox. Nothing here dispatches a real rider or charges money. You will make four requests:

Ask for a delivery quote.
Create a simulated delivery.
Move it to the assigned status.
Read its current status and event history.

Run each command in a terminal. Lines beginning with export save a value only for that terminal window.

1. Copy your test key

In the developer portal, create an application and then create a test key. Copy the full key when it appears; it is shown only once. Replace paste_your_complete_test_key_here below, then run both lines:

export HAULSTOW_BASE_URL="https://sandbox.developer.haulstow.co/v1"
export HAULSTOW_API_KEY="hsg_test_key_paste_your_complete_test_key_here"

Your key must begin with hsg_test_key_. Keep the quotation marks.

2. Calculate a quote

This request asks, “What would a bike delivery between these two coordinates cost?” It does not create a delivery, so it does not need an idempotency key.

curl --request POST "$HAULSTOW_BASE_URL/quotes" \
  --header "Authorization: Bearer $HAULSTOW_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "pickup": {"latitude": 5.6037, "longitude": -0.1870},
    "dropoff": {"latitude": 5.6698, "longitude": -0.1695},
    "vehicle_type": "bike"
  }'

You should receive a response shaped like this:

{
  "success": true,
  "statusCode": 200,
  "message": "Quote calculated",
  "data": {
    "environment": "test",
    "simulated": true,
    "vehicle_type": "bike",
    "currency": "GHS",
    "distance_km": 7.6,
    "distance_source": "sandbox_fixture",
    "fee": 40,
    "requires_custom_quote": false
  }
}

Your exact distance_km may differ slightly. A sandbox trip over 15 km returns "requires_custom_quote": true and "fee": null.

If you receive INVALID_API_KEY, make sure you copied the entire key and included Bearer before it. If you receive ENVIRONMENT_MISMATCH, you used a live key with the sandbox URL or a test key with the live URL.

3. Create a delivery

This example creates the recipient and address inside the delivery request. HaulStow returns reusable recipient and address IDs in the response. The Idempotency-Key value identifies this one create action. If the command times out, run the same command with the same key. HaulStow will return the first result instead of creating a duplicate.

curl --request POST "$HAULSTOW_BASE_URL/deliveries" \
  --header "Authorization: Bearer $HAULSTOW_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: shop-order-1842-create-v1" \
  --data '{
    "external_id": "shop-order-1842",
    "recipient": {
      "name": "Ama Mensah",
      "phone_number": "+233245412312",
      "address": {
        "label": "Home",
        "address": "15 Independence Avenue, Accra",
        "latitude": 5.5600,
        "longitude": -0.2057,
        "municipality": "Accra Metropolitan",
        "delivery_notes": "Call when you arrive"
      }
    },
    "pickup": {
      "name": "Osu Store",
      "contact": "+233200000001",
      "address": "Oxford Street, Osu, Accra",
      "latitude": 5.5560,
      "longitude": -0.1820
    },
    "payment": {"type": "cod", "goods_value": 185},
    "vehicle_type": "bike"
  }'

The response contains a delivery ID beginning with dlv_:

{
  "success": true,
  "statusCode": 201,
  "message": "Delivery created",
  "data": {
    "id": "dlv_3f1a821cdb58498cbb52f4706545a089",
    "external_id": "shop-order-1842",
    "environment": "test",
    "simulated": true,
    "status": "booked",
    "recipient": {
      "id": "rcp_..."
    },
    "dropoff": {
      "id": "adr_..."
    }
  }
}

Copy the complete data.id value and save it in your terminal:

export HAULSTOW_DELIVERY_ID="dlv_3f1a821cdb58498cbb52f4706545a089"

Replace the example ID with the one from your response.

4. Trigger a sandbox event

Real deliveries change status when HaulStow operations and riders do their work. In the sandbox, you trigger those changes yourself. Move the delivery from booked to assigned:

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: shop-order-1842-assigned-v1" \
  --data '{"status":"assigned"}'

The next valid states are:

booked -> assigned -> picked_up -> in_transit -> delivered

Move one step at a time. Skipping from assigned directly to delivered returns SANDBOX_TRANSITION_INVALID.

5. Check the delivery

Get the latest delivery snapshot:

curl "$HAULSTOW_BASE_URL/deliveries/$HAULSTOW_DELIVERY_ID" \
  --header "Authorization: Bearer $HAULSTOW_API_KEY"

Get its complete public event history:

curl "$HAULSTOW_BASE_URL/deliveries/$HAULSTOW_DELIVERY_ID/events" \
  --header "Authorization: Bearer $HAULSTOW_API_KEY"

If you configured a webhook endpoint, every accepted sandbox transition also queues a signed webhook. The payload and signature format are the same in live mode.

You are ready for the next step

You now know the basic request flow. Next:

Learn why retries need an idempotency key.
Learn how to get automatic updates with webhooks.
See how to create and reuse recipients in the API reference.
Use common errors if a command fails.

Get started

Core concepts

Endpoint reference

1. Copy your test key

2. Calculate a quote

3. Create a delivery

4. Trigger a sandbox event

5. Check the delivery

You are ready for the next step

​1. Copy your test key

​2. Calculate a quote

​3. Create a delivery

​4. Trigger a sandbox event

​5. Check the delivery

​You are ready for the next step

1. Copy your test key

2. Calculate a quote

3. Create a delivery

4. Trigger a sandbox event

5. Check the delivery

You are ready for the next step