API reference

An endpoint is one HTTP method and path, such as GET /deliveries. Add the path to the base URL:

Sandbox base URL + path
https://sandbox.developer.haulstow.co/v1 + /deliveries

Complete URL
https://sandbox.developer.haulstow.co/v1/deliveries

The interactive endpoint pages in the navigation contain every field, example, header, and possible response. This page helps you choose the endpoint you need.

Choose an endpoint

Method	Path	Required scope
`POST`	`/quotes`	`quotes:read`
`POST`	`/recipients`	`recipients:write`
`GET`	`/recipients`	`recipients:read`
`GET`	`/recipients/{recipient_id}`	`recipients:read`
`POST`	`/recipients/{recipient_id}/addresses`	`recipients:write`
`GET`	`/recipients/{recipient_id}/addresses`	`recipients:read`
`GET`	`/recipient-addresses/{address_id}`	`recipients:read`
`POST`	`/deliveries`	`deliveries:write`
`POST`	`/deliveries/bulk`	`deliveries:write`
`GET`	`/deliveries`	`deliveries:read`
`GET`	`/deliveries/{delivery_id}`	`deliveries:read`
`GET`	`/deliveries/{delivery_id}/events`	`deliveries:read`
`POST`	`/deliveries/{delivery_id}/cancel`	`deliveries:write`
`POST`	`/test-helpers/deliveries/{delivery_id}/transition`	`deliveries:write`, sandbox only
`POST`	`/test-helpers/deliveries/{delivery_id}/simulate`	`deliveries:write`, sandbox only
`DELETE`	`/test-helpers/deliveries/{delivery_id}/simulation`	`deliveries:write`, sandbox only

GET means read data. POST means calculate, create, or change something. DELETE means stop or remove something. Text inside braces is a value you replace. For example:

/deliveries/{delivery_id}
              becomes
/deliveries/dlv_3f1a821cdb58498cbb52f4706545a089

Common workflows

Create a delivery quickly

Use POST /deliveries with an inline recipient. This creates or reuses the recipient and address while creating the delivery. See the quickstart.

Reuse a recipient on many deliveries

POST /recipients and save the returned rcp_... ID.
POST /recipients/{recipient_id}/addresses and save the returned adr_... ID.
Send both IDs in each later POST /deliveries request.

Use this approach when the same customer receives multiple deliveries.

Save a pickup location

If you ship from the same shop or warehouse every day, save it once and pass its ID instead of the full pickup object. Quotes accept pickup_location_id too.

curl --request POST "$HAULSTOW_BASE_URL/pickup-locations" \
  --header "Authorization: Bearer $HAULSTOW_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: pickup-osu-store-v1" \
  --data '{
    "name": "Osu Store",
    "contact": "+233200000001",
    "address": "Oxford Street, Osu, Accra",
    "latitude": 5.5560,
    "longitude": -0.1820
  }'

Then book with "pickup_location_id": "pkp_..." in place of pickup. On live keys, pickup locations are your business’s warehouses, so they also show in the HaulStow merchant app.

Create many deliveries at once

Use POST /deliveries/bulk to send 1–100 deliveries in one request. Each item in deliveries is exactly the body you would send to POST /deliveries. See bulk deliveries for the full guide.

curl --request POST "$HAULSTOW_BASE_URL/deliveries/bulk" \
  --header "Authorization: Bearer $HAULSTOW_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: morning-batch-2026-08-20-v1" \
  --data '{
    "deliveries": [
      {
        "external_id": "shop-order-1842",
        "recipient": {
          "name": "Ama Mensah",
          "phone_number": "+233245412312",
          "address": {
            "address": "15 Independence Avenue, Accra",
            "latitude": 5.5600,
            "longitude": -0.2057
          }
        },
        "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"
      },
      {
        "external_id": "shop-order-1843",
        "recipient_id": "rcp_3f1a821cdb58498cbb52f4706545a089",
        "recipient_address_id": "adr_78de60204f574a64be88ba9bd94a049f",
        "pickup": {
          "name": "Osu Store",
          "contact": "+233200000001",
          "address": "Oxford Street, Osu, Accra",
          "latitude": 5.5560,
          "longitude": -0.1820
        },
        "payment": {"type": "delivery_only"},
        "vehicle_type": "bike"
      }
    ]
  }'

HaulStow checks every item first. If any item is invalid, nothing is created and you receive 422 BULK_VALIDATION_FAILED. Otherwise each item is created on its own, so one failure does not stop the rest. The response is 201 when every item was created and 207 when at least one failed:

{
  "success": true,
  "statusCode": 207,
  "message": "Some deliveries failed",
  "data": {
    "created": 1,
    "failed": 1,
    "results": [
      {
        "index": 0,
        "status": "created",
        "delivery": {
          "id": "dlv_3f1a821cdb58498cbb52f4706545a089",
          "external_id": "shop-order-1842",
          "status": "booked"
        }
      },
      {
        "index": 1,
        "status": "failed",
        "error": {
          "code": "EXTERNAL_ID_CONFLICT",
          "message": "External ID is already in use"
        }
      }
    ]
  }
}

index is the item’s position in your deliveries array, starting at 0. One bulk call counts as one request against your rate limit.

Show a delivery-history page

Call GET /deliveries with filters such as status or external_id.
Follow meta.next_cursor while meta.has_more is true.
Call GET /deliveries/{delivery_id} for one full snapshot.
Call GET /deliveries/{delivery_id}/events for its public timeline.

Cancel a delivery

Call POST /deliveries/{delivery_id}/cancel. Cancellation works only before pickup. Cancelling an already-cancelled delivery returns the same cancelled delivery. Cancelling after pickup returns 409 DELIVERY_NOT_CANCELLABLE.

Visibility rules

Recipients and addresses belong to the HaulStow business, so two developer applications for the same business can reuse them. Deliveries belong to the developer application that created them. Another application receives 404 instead of learning that the delivery exists. The public delivery model intentionally excludes cargo contents, line items, rider details, internal operational state, platform notes, settlement data, and fee overrides.

IDs and filters

The letters at the beginning of an ID tell you what it identifies:

Prefix	Resource	Example
`rcp_`	Recipient	`rcp_3f1a821cdb58498cbb52f4706545a089`
`adr_`	Recipient address	`adr_3f1a821cdb58498cbb52f4706545a089`
`dlv_`	Delivery	`dlv_3f1a821cdb58498cbb52f4706545a089`
`evt_`	Delivery event	`evt_3f1a821cdb58498cbb52f4706545a089`

Copy IDs exactly. Do not remove the prefix or try to use an internal order ID.

Filters and pages

Delivery lists accept status, external_id, created_after, created_before, cursor, and limit. Recipient lists accept cursor and limit. Cursors are opaque and must be passed back unchanged. Example: list the first 25 in-transit deliveries:

curl "$HAULSTOW_BASE_URL/deliveries?status=in_transit&limit=25" \
  --header "Authorization: Bearer $HAULSTOW_API_KEY"

Example: find the delivery attached to your own order number:

curl "$HAULSTOW_BASE_URL/deliveries?external_id=shop-order-1842" \
  --header "Authorization: Bearer $HAULSTOW_API_KEY"

See polling and pagination for how to use next_cursor.

Get started

Core concepts

Endpoint reference

Choose an endpoint

Common workflows

Create a delivery quickly

Reuse a recipient on many deliveries

Save a pickup location

Create many deliveries at once

Show a delivery-history page

Cancel a delivery

Visibility rules

IDs and filters

Filters and pages

​Choose an endpoint

​Common workflows

​Create a delivery quickly

​Reuse a recipient on many deliveries

​Save a pickup location

​Create many deliveries at once

​Show a delivery-history page

​Cancel a delivery

​Visibility rules

​IDs and filters

​Filters and pages

Choose an endpoint

Common workflows

Create a delivery quickly

Reuse a recipient on many deliveries

Save a pickup location

Create many deliveries at once

Show a delivery-history page

Cancel a delivery

Visibility rules

IDs and filters

Filters and pages