Partner Shipping API

Authentication

All API requests require an x-partner-key header containing your API key. Keys are issued by the Haulstow admin team. Contact us at info@haulstow.co to request access.

curl -X POST https://www.haulstow.co/api/partner/shipping/quote \
  -H "Content-Type: application/json" \
  -H "x-partner-key: hst_abc123def456ghi789" \
  -d '{"pickupAddress": "...", "deliveryAddress": "..."}'

Request Body

Example

curl -X POST https://www.haulstow.co/api/partner/shipping/quote \
  -H "Content-Type: application/json" \
  -H "x-partner-key: hst_abc123def456ghi789" \
  -d '{
    "pickupAddress": "Osu Oxford Street, Accra",
    "deliveryAddress": "Achimota Mall, Accra",
    "vehicleType": "bike"
  }'

Response

{
  "distanceKm": 8.4,
  "durationMinutes": 25,
  "price": 18.50,
  "currency": "GHS",
  "vehicleType": "bike"
}

Request Body

Example

curl -X POST https://www.haulstow.co/api/partner/shipping/create-order \
  -H "Content-Type: application/json" \
  -H "x-partner-key: hst_abc123def456ghi789" \
  -d '{
    "pickupAddress": "Osu Oxford Street, Accra",
    "deliveryAddress": "Achimota Mall, Accra",
    "deliveryRecipient": "Kwame Mensah",
    "deliveryContact": "+233201234567",
    "cargoDescription": "Electronics package",
    "vehicleType": "bike",
    "partnerOrderId": "ORD-2024-001"
  }'

Response

{
  "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "partnerId": "p9r8q7w6-e5t4-3210-zyxw-vu0987654321",
  "status": "booked",
  "price": 18.50,
  "currency": "GHS",
  "distanceKm": 8.4,
  "trackingUrl": "https://www.haulstow.co/track/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Query Parameters

Example

curl "https://www.haulstow.co/api/partner/shipping/status?orderId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-partner-key: hst_abc123def456ghi789"

Response

{
  "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "dispatched",
  "paymentStatus": "paid",
  "pickupAddress": "Osu Oxford Street, Accra",
  "deliveryAddress": "Achimota Mall, Accra",
  "deliveryRecipient": "Kwame Mensah",
  "deliveryFee": 18.50,
  "distanceKm": 8.4,
  "riderName": "Kofi Asante",
  "hasRider": true,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:45:00Z",
  "trackingUrl": "https://www.haulstow.co/track/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Statuses

Request Body

Example

curl -X POST https://www.haulstow.co/api/partner/shipping/cancel \
  -H "Content-Type: application/json" \
  -H "x-partner-key: hst_abc123def456ghi789" \
  -d '{
    "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Response

{
  "success": true,
  "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "cancelled"
}

Query Parameters

Example

curl "https://www.haulstow.co/api/partner/places/autocomplete?input=Osu%20Oxford" \
  -H "x-partner-key: hst_abc123def456ghi789"

Response

{
  "predictions": [
    {
      "placeId": "ChIJx8k9tmqKOxARkVcUnSN_wgg",
      "description": "Oxford Street, Osu, Accra, Ghana"
    },
    {
      "placeId": "ChIJy7k2tmqKOxARpVcUnSN_wgg",
      "description": "Oxford Street Mall, Osu, Accra, Ghana"
    }
  ]
}

Query Parameters

Example

curl "https://www.haulstow.co/api/partner/places/details?placeId=ChIJx8k9tmqKOxARkVcUnSN_wgg" \
  -H "x-partner-key: hst_abc123def456ghi789"

Response

{
  "formattedAddress": "Oxford Street, Osu, Accra, Ghana",
  "street": "Oxford Street",
  "city": "Accra",
  "state": "Greater Accra",
  "country": "Ghana",
  "zip": "",
  "lat": 5.5560,
  "lng": -0.1789
}

Webhooks

Configure a webhook URL to receive real-time updates when an order status changes. Haulstow will send a POST request to your URL with a JSON payload. Failed deliveries are retried up to 3 times.

Events

Payload

{
  "event": "order.delivered",
  "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "status": "delivered",
    "riderName": "Kofi Asante",
    "deliveredAt": "2025-01-15T11:30:00Z"
  },
  "timestamp": "2025-01-15T11:30:05Z"
}

Signature Verification

Every webhook request includes an x-haulstow-signature header. Verify it using your webhook secret to ensure the request is authentic.

// Node.js verification example
const crypto = require('crypto');

function verifyWebhook(req, rawBody) {
  const secret = process.env.HAULSTOW_WEBHOOK_SECRET;
  const signature = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  const expected = `sha256=${signature}`;
  return req.headers['x-haulstow-signature'] === expected;
}

Error Handling

All errors return a JSON object with an error field and an appropriate HTTP status code.

Error Response Format

{
  "error": "Missing required field: deliveryContact"
}