Book a trip

Prerequisites
Get quotes
Book a trip
Trip updates
Trip completion

With a quote selected, the next step is to confirm booking of that quote with the supplying fleet.

Book a trip

A booking for the selected quote is made using the Bookings API

Make a POST request to the /bookings endpoint, sending a valid quote id. Some additional details such as the main passenger’s name and a phone number are required. See the API reference for details and examples.

Note: If you attempt to book a trip using an expired Quote ID the bookings endpoint will respond with a HTTP Status Code of 400 and the error message of "Could not book trip (attempt to book an expired quote)". If this happens, a fresh quote must be requested as in the prior step.

After a request, you can monitor the progress of the booking by calling the /bookings/{id}. If you are only interested in the status of the booking you can also call /bookings/{id}/status.

The status of the Booking Request will be one of the following:

Booking status	Description
REQUESTED	>>>DEPRECATED<<< The request is matching to the most efficient available driver (By Dispatch).
CONFIRMED	The booking request has been received and accepted by the Fleet. If it is an ASAP booking, the Fleet is searching (allocating) for the next available driver. If it is Pre-book, the Fleet will allocate a driver closer to pickup time. This does not mean that the Fleet will guarantee pickup. A trip may still be cancelled due to non-availability.
DRIVER_EN_ROUTE	A driver is “en route” to the start location. This state can occur multiple times in case of a driver re-assignment.
ARRIVED	The driver has arrived at the pickup location. This state might be skipped in some cases.
POB	Passenger on-board and the ride has “started”.
COMPLETED	Passenger has reached their destination.
NO_DRIVERS_AVAILABLE	The request was unfulfilled because no driver was available.
DRIVER_CANCELLED	The request has been cancelled by Dispatch or driver.
BOOKER_CANCELLED	The request has been cancelled by the rider.
KARHOO_CANCELLED	The request has been cancelled by Karhoo.
FAILED	There was an internal error with the booking.

Related tasks

As part of the trip booking process, the user might need to complete additional, related tasks.

Payment details

Before booking a journey, users typically need to provide payment details. Many of Karhoo's Demand Partners have their own payment solutions and therefore integrate their own payment flow into the application. Details on settling payments with Karhoo and information about Karhoo's Payment API are available when onboarding to the Karhoo Production environment. Please reach out to the Karhoo team for details.

Following a booking

The Follow a Booking endpoint returns booking information for the passenger to access without a need to log in. This can be useful for giving passengers information on future trips.

Search booking history

The Search Booking History API allows for giving end users the ability to review prior trips taken.

See the Bookings API reference for more endpoints and possibilities to create a rich end user booking experience.

Reference

Service	API reference	Errors reference
Bookings	Bookings	Bookings Errors

Troubleshooting

Some potential errors you might encounter are:

Error	Solution
Invalid request payload	Check the request body for invalid parameter names or values.
Could not book trip (attempt to book an expired quote)	Requote the trip.