Create a delivery trip
POST/v2/trips
Paid API plans only (basic, pro, enterprise).
A trip follows one courier to one destination. Send the courier's
position with POST /v2/trips/{id}/location and AfriHex keeps the
ETA up to date from road data and Ghana traffic, moves the trip
through its statuses and sends webhooks:
| Status | When |
|---|---|
pending | Created, courier not moving yet |
started | First location ping (or PATCH status=started) |
approaching | ETA at or under approaching_threshold_s |
arrived | Within arrival_radius_m of the destination |
completed / canceled | You set it with PATCH |
expired | Still open at expires_at (default 24 h after creation) |
returning | A failed attempt with next_action: return; ends with PATCH status=returned |
returned | Back with the sender |
failed | A failed attempt with next_action: stop |
Webhook events (subscribe with POST /v2/webhooks/configure):
trip.created, trip.started, trip.approaching, trip.arrived,
trip.delayed (ETA more than 5 minutes past scheduled_arrival_at),
trip.completed, trip.completed_away_from_destination (completed
while the last ping was far from the address), trip.canceled,
trip.expired, and for failed deliveries trip.attempt_failed,
trip.rescheduled, trip.return_started, trip.returned,
trip.failed, and for cash on delivery trip.collection_recorded,
trip.collection_voided and trip.amount_to_collect_updated. Each payload has event, occurred_at, trip and
detail.
The response includes tracking_url, a page the recipient can open to
follow the delivery. It is shown only once; AfriHex stores a hash.
Make a new one with POST /v2/trips/{id}/tracking-link.
The destination takes any location form, including a GhanaPostGPS
gps_code. Call this from your server, not a browser or rider app
(see Authentication).
Request
Responses
- 201
- 400
- 403
Trip created, with its one-time tracking_url
Invalid body, destination or duplicate external_id (INVALID_BODY, VALIDATION_ERROR)
Not on a paid API plan (PLAN_UPGRADE_REQUIRED)