Skip to main content

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:

StatusWhen
pendingCreated, courier not moving yet
startedFirst location ping (or PATCH status=started)
approachingETA at or under approaching_threshold_s
arrivedWithin arrival_radius_m of the destination
completed / canceledYou set it with PATCH
expiredStill open at expires_at (default 24 h after creation)
returningA failed attempt with next_action: return; ends with PATCH status=returned
returnedBack with the sender
failedA 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​

Trip created, with its one-time tracking_url