curl --request POST \
  --url https://developer.haulstow.co/v1/deliveries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "external_id": "shop-order-1842",
  "recipient": {
    "name": "Ama Mensah",
    "phone_number": "+233245412312",
    "address": {
      "label": "Home",
      "address": "15 Independence Avenue, Accra",
      "latitude": 5.56,
      "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.556,
    "longitude": -0.182
  },
  "payment": {
    "type": "cod",
    "goods_value": 185
  },
  "vehicle_type": "bike",
  "delivery_instructions": "Leave with the front desk if authorized"
}
'

{
  "success": true,
  "statusCode": 201,
  "message": "Delivery created",
  "data": {
    "id": "dlv_3f1a821cdb58498cbb52f4706545a089",
    "external_id": "shop-order-1842",
    "reference": "H-RS83223",
    "environment": "live",
    "simulated": false,
    "status": "booked",
    "recipient": {
      "id": "rcp_3f1a821cdb58498cbb52f4706545a089",
      "name": "Ama Mensah",
      "phone_number": "+233245412312"
    },
    "pickup": {
      "name": "Osu Store",
      "contact": "+233200000001",
      "address": "Oxford Street, Osu, Accra",
      "latitude": 5.556,
      "longitude": -0.182
    },
    "dropoff": {
      "id": "adr_78de60204f574a64be88ba9bd94a049f",
      "label": "Home",
      "address": "15 Independence Avenue, Accra",
      "latitude": 5.56,
      "longitude": -0.2057,
      "municipality": "Accra Metropolitan",
      "delivery_notes": "Call when you arrive"
    },
    "payment": {
      "type": "cod",
      "goods_value": 185
    },
    "vehicle_type": "bike",
    "currency": "GHS",
    "delivery_fee": 20,
    "requires_custom_quote": false,
    "tracking_url": "https://track.haulstow.co/H-RS83223",
    "created_at": "2026-08-20T14:20:00Z",
    "updated_at": "2026-08-20T14:20:00Z"
  }
}

Deliveries

Create a delivery

Creates one delivery using either existing recipient/address IDs or one inline recipient. The two recipient shapes are mutually exclusive.

The pickup is likewise either an inline pickup or a saved pickup_location_id from pickup locations. Sending both returns 422 PICKUP_SHAPE_CONFLICT. An unknown location returns 422 PICKUP_LOCATION_NOT_FOUND, an inactive one 422 PICKUP_LOCATION_INACTIVE, and one missing a contact or coordinates 422 PICKUP_LOCATION_INCOMPLETE.

This public contract is content-opaque: it accepts no line items, product contents, declared value, rider, vehicle, fee override, business_id, or operational status.

With a test key you can add a sandbox object to make the new delivery play out a real-world scenario by itself. See Automatic simulation. A live key that sends sandbox gets 400 SANDBOX_ONLY_FIELD and nothing is created. In the sandbox, a scenario that does not fit the payment type returns 409 SIMULATION_NOT_APPLICABLE, and starting more than 100 running simulations for one application returns 429 SIMULATION_LIMIT.

POST

deliveries

curl --request POST \
  --url https://developer.haulstow.co/v1/deliveries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "external_id": "shop-order-1842",
  "recipient": {
    "name": "Ama Mensah",
    "phone_number": "+233245412312",
    "address": {
      "label": "Home",
      "address": "15 Independence Avenue, Accra",
      "latitude": 5.56,
      "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.556,
    "longitude": -0.182
  },
  "payment": {
    "type": "cod",
    "goods_value": 185
  },
  "vehicle_type": "bike",
  "delivery_instructions": "Leave with the front desk if authorized"
}
'

{
  "success": true,
  "statusCode": 201,
  "message": "Delivery created",
  "data": {
    "id": "dlv_3f1a821cdb58498cbb52f4706545a089",
    "external_id": "shop-order-1842",
    "reference": "H-RS83223",
    "environment": "live",
    "simulated": false,
    "status": "booked",
    "recipient": {
      "id": "rcp_3f1a821cdb58498cbb52f4706545a089",
      "name": "Ama Mensah",
      "phone_number": "+233245412312"
    },
    "pickup": {
      "name": "Osu Store",
      "contact": "+233200000001",
      "address": "Oxford Street, Osu, Accra",
      "latitude": 5.556,
      "longitude": -0.182
    },
    "dropoff": {
      "id": "adr_78de60204f574a64be88ba9bd94a049f",
      "label": "Home",
      "address": "15 Independence Avenue, Accra",
      "latitude": 5.56,
      "longitude": -0.2057,
      "municipality": "Accra Metropolitan",
      "delivery_notes": "Call when you arrive"
    },
    "payment": {
      "type": "cod",
      "goods_value": 185
    },
    "vehicle_type": "bike",
    "currency": "GHS",
    "delivery_fee": 20,
    "requires_custom_quote": false,
    "tracking_url": "https://track.haulstow.co/H-RS83223",
    "created_at": "2026-08-20T14:20:00Z",
    "updated_at": "2026-08-20T14:20:00Z"
  }
}

Authorizations

Authorization

string

header

required

A business-bound HaulStow API key. Send Authorization: Bearer hsg_live_key_... to the live server or a hsg_test_key_... key to the sandbox server. Never expose this key in a browser.

Headers

X-Request-ID

string

Optional caller correlation ID. Use 1–128 ASCII letters, digits, ., _, -, or :. Invalid values are replaced. The accepted/generated value is returned in the response.

Required string length: 1 - 128

Pattern: ^[A-Za-z0-9._:-]+$

Idempotency-Key

string

required

A unique key for this logical mutation. Retained for 24 hours.

Required string length: 8 - 255

Body

application/json

Inline pickup
Saved pickup location
Inline pickup
Saved pickup location

recipient_id

string

required

Pattern: ^rcp_[a-f0-9]{32}$

Example:

"rcp_3f1a821cdb58498cbb52f4706545a089"

recipient_address_id

string

required

Pattern: ^adr_[a-f0-9]{32}$

Example:

"adr_78de60204f574a64be88ba9bd94a049f"

pickup

object

required

Show child attributes

payment

object

required

Option 1
Option 2

Show child attributes

vehicle_type

enum<string>

required

Available options:

bike,

minivan

Example:

"bike"

external_id

string

Unique within the authenticated application when supplied.

Required string length: 1 - 128

recipient

object

Show child attributes

pickup_location_id

string

Pattern: ^pkp_[a-f0-9]{32}$

Example:

"pkp_9b2f0c1e4d5a4b6c8e7f1a2b3c4d5e6f"

delivery_instructions

string

Maximum string length: 500

sandbox

object

Sandbox only. Makes the delivery play out a scenario by itself.

Show child attributes

Response

Delivery created.

success

boolean

required

statusCode

enum<integer>

required

Available options:

200,

201

message

string

required

data

object

required

Show child attributes

Get started

Core concepts

Endpoint reference

Create a delivery

Authorizations

Headers

Body

Response