Guide: connect an OTA or broker

This guide is for sales channels, such as online travel agencies, brokers and tour operators, that sell a rental company's vehicles and send the bookings into its HQ account.
The rental company gives you an encoded API token of a user created only for you.

The flow is: load reference data, search, optionally price extras, book, then keep the booking in sync.

Step 1 - Load reference data once a day

GET /fleets/locations returns the active locations with their IDs, address, opening hours and is_airport.

GET /fleets/vehicle-classes returns the vehicle classes; send only_available_on_website=1 to get only the ones the rental company sells online.

GET /fleets/additional-charges returns the extras, insurance and fees.

Map the HQ location and vehicle class IDs to your own codes once and store the mapping.

Step 2 - Search availability and prices

Send Accept: application/vnd.api.v2+json; without it this path returns 404.

Parameter	Meaning
`pick_up_date`, `return_date`	Required. `YYYY-MM-DD HH:mm`, in the API user's time zone. The return must be after the pick-up.
`pick_up_location_id`, `return_location_id`	Required. Active location IDs. The pick-up location decides the branch, and so the prices.
`rate_code`	Optional. Price with this rate type, for example a rate agreed for your channel. It must exist.
`customer_id`	Optional. Apply the prices of this customer.
`language`	Optional. Language of the class descriptions.

data has one item per active vehicle class shown on the website that has a rate for those dates.
Each item has:

status: available or unavailable.
A class is unavailable when no unit is free or the season does not allow a rental of that length.

vehicle_class_id, name, sippCode, description, seats, bags, doors.

total_price_with_mandatory_charges_and_taxes: the price to show, as a Money object (see Dates, time zones and money).

price.total_days, price.base_price and the daily breakdown in price.details.

security_deposit, distance_limits, age_ranges, charges_for_age_limits and the charges for pick-up or return outside opening hours.

rate_type: the rate type used, with its code and the extras it includes.

A pick-up or return outside the location's opening hours returns a validation error, unless the location accepts bookings outside its opening hours.

Step 3 - Price extras and the driver's age (optional)

To show the exact total with extras before booking, call POST /car-rental/reservations/additional-charges with the same dates as separate fields (pick_up_date, pick_up_time, return_date, return_time), pick_up_location, return_location, vehicle_class_id, the selected additional_charges, customer_age or customer_birthdate, and the same rate_code you searched with, if any.
data.total holds the total, the amount due and the security deposit.
Nothing is saved.
This endpoint allows 60 requests per minute per user (see Rate limits and idempotency).

Step 4 - Create the booking

Parameter	Meaning
`ota_reservation_type`	Your channel name, stored in lowercase.
`ota_reservation_id`	Your booking reference. It is stored only together with `ota_reservation_type`.
`validate_duplicated_ota_reservation_id`	`1` refuses the booking when any reservation, from any channel, already has the same `ota_reservation_id`.
`customer_first_name`, `customer_last_name`, `customer_email`, ...	The customer. A contact with the same first name, last name and email is reused; otherwise a new one is created.
`rate_code`	The rate type to price with, as in the search.
`prepaid_amount`, `prepaid_payment_method`	What the customer already paid you, recorded as a payment (method `Cash` by default).
`comments[]`	Notes for the rental company, such as a flight number or special requests.
`skip_confirmation_email`	`1` when you send your own confirmation, so HQ does not email the customer.

Store data.reservation.id, the HQ reservation ID, next to your reference.
You cannot search reservations by your reference later, so this mapping is how you find the booking again.

If the request times out, send it again with the same Idempotency-Key.
If the retry returns HTTP 422, see Rate limits and idempotency for what to do next.

Step 5 - Read the booking

GET /car-rental/reservations/{reservation_id} returns the reservation with its status, customer, drivers, assigned vehicle, charges and totals.

Step 6 - Change the booking

POST /car-rental/reservations/{reservation_id}/update with only the values that change, for example new dates (pick_up_date with pick_up_time, return_date with return_time), locations, vehicle class or extras.
The reservation is priced again.

additional_charges replaces the whole selection of extras; mandatory charges are added back.

If you leave out additional_drivers, every additional driver is removed; send their full list to keep them.

To pass a request to the rental company without changing the booking, add a note with POST /car-rental/reservations/{reservation_id}/comments and comment.

Step 7 - Cancel the booking

POST /car-rental/reservations/{reservation_id}/cancelled cancels the booking.
See HQ concepts and glossary for the statuses a booking can be cancelled from.

Step 8 - Hear about changes

The rental company can send you a Reservation webhook with the action Updated and the filter ota_reservation_type:equal:acme, so that you receive only your bookings (see Webhooks).

Errors to handle

Business rule errors, such as the two below, come back with HTTP 200 and "success": false; read errors.error_message.

Missing or invalid fields, including a time outside opening hours in the search, come back with HTTP 422 and the messages per field in errors (see Errors).

"The selected vehicle class is not available anymore": the class sold out between your search and the booking.
Search again, and book with a new Idempotency-Key.

"Reservation Already Exists": you sent validate_duplicated_ota_reservation_id=1 and a reservation with that ota_reservation_id already exists.

Step 1 - Load reference data once a day#

Step 2 - Search availability and prices#

Step 3 - Price extras and the driver's age (optional)#

Step 4 - Create the booking#

Step 5 - Read the booking#

Step 6 - Change the booking#

Step 7 - Cancel the booking#

Step 8 - Hear about changes#

Errors to handle#