Guide: build a booking engine on your website
The flow follows the steps of HQ's own booking engine: dates, vehicle class, extras, price, customer, driver's license, and confirmation.
The reservation is created only in the last step, and no step remembers what an earlier one received, so send the full booking context again on every call: dates, times, locations,
brand_id, vehicle_class_id from step 3 on, and the selected additional_charges from step 4 on.Step 6 does save the customer, and the reservation attempt below is recorded from step 2 on.
Before you start
For administrators, and for roles that do not set Can skip date validations to Deny, step 2 skips the minimum and maximum rental period, the advance booking time and the allowed times.
For a public website, use a user whose role sets it to Deny, or enforce those rules yourself.
reservation_attempt_uuid, your own identifier for the visitor's session, on every step.HQ records the booking as a reservation attempt, so you can follow up on abandoned bookings, and closes it when the booking is confirmed.
Step 1 - Build the dates form
GET /car-rental/reservations/dates?brand_id=1 returns what you need for the first form: pick-up and return locations, their opening hours, default and minimum dates, rental period limits and the age ranges you can send later as customer_age.Step 2 - Validate the dates and list vehicle classes
POST /car-rental/reservations/dates with pick_up_date, pick_up_time, return_date, return_time, pick_up_location, return_location and brand_id validates them against your opening hours and rental rules.It returns the vehicle classes that have a rate for the period, with their availability and price.
Offer only the classes with
availability.selectable true and availability.quantity greater than 0.Step 3 - List the extras
GET /car-rental/reservations/additional-charges with the booking context and the chosen vehicle_class_id returns the extras, insurances and fees that can be added, with their prices.mandatory true are always included.selected true, are added by HQ on steps 4, 6 and 8 even when you leave them out of additional_charges[].When the visitor can untick them, send
includes_selected_by_default_additional_charges=false (the string false) on those steps and list in additional_charges[] every charge the visitor kept.{id} for an only_one charge, and a key of its dropdown_options ({id}_{quantity}) for a multiple charge.A charge with
distance_package_rates true is a mileage package: send a key of its distance_package ({id}_{distance}, such as 12_100) instead.With only
{id}, no package is matched and the charge is priced at zero.Step 4 - Price the selection
POST /car-rental/reservations/additional-charges with the booking context and additional_charges[] returns the full price breakdown.data.total holds the total, the amount due and the security deposit, ready for your summary.HQ can add more charges here, such as location or outside-hours fees, so treat
selected_additional_charges in this response as the final selection.coupon_code; separate several codes with commas.An invalid code returns a business-rule error, so show its message next to the coupon field.
manual_discount, with manual_discount_is_percentage=1 for a percentage, needs the role permission Can add Manual Discount? and is meant for internal tools, not for a public website.Step 5 - Build the customer form
GET /car-rental/reservations/fields/customer returns the fields of your customer form, in order, with their label, type and required flag.It also returns
contact_category_id, the contact category your customers are saved in.When it is null, no customer category is set in the Car Rental settings, and step 6 returns 404 until one is set.
The response has no
success envelope.Step 6 - Save the customer
POST /car-rental/reservations/customer with the booking context and the form values saves the customer and checks the driver against the age and driver's license rules of the vehicle class.Send
first_name, last_name and birthdate by name, and every other field as field_<id> (see Custom fields and item types).data.customer.id: it is the customer_id of the booking.contact_id, a new contact is created on every call, even when a contact with the same email exists.When the visitor goes back and edits the form, send the stored ID as
contact_id, or identify the visitor with external_contact_type and external_contact_id from your own system.When you update a contact this way, the form fields you leave out are cleared; send
ignore_empty_fields=1 to keep the ones you do not send.Step 7 - Upload the driver's license (optional)
POST /files/upload as multipart/form-data attaches the license image to the customer:filename is required and becomes the file's label.item_type is contacts. followed by the contact_category_id from step 5.item_id is the customer ID from step 6.field_id is the id of the license field in step 5.POST /files/upload.Step 8 - Confirm the booking
POST /car-rental/reservations/confirm with the booking context, the same additional_charges[] and coupon_code, and customer_id creates the reservation.Send an
Idempotency-Key header, so that a retry after a timeout does not create a second booking (see Rate limits and idempotency).Store
data.reservation.id.skip_confirmation_email=1 when your website sends its own.Take the payment
return_payment_link=1, payment_method_id and payment_external_redirect, the page the customer returns to after paying.The response has the link in
data.transaction.payment_link.See Guide: take payments for these fields, for how to choose the payment method and for how to check that the customer paid.
HQ allows its payment page to be framed.
Some gateways change their page during the payment, for example for 3-D Secure, so test every gateway you use.
Change a booking
POST /car-rental/reservations/{reservation_id}/update changes a booking and prices it again.Send only what changes:
| Change | Send |
|---|---|
| Dates | pick_up_date with pick_up_time, return_date with return_time. A date without its time is ignored. |
| Locations | pick_up_location and return_location, or custom with pick_up_location_custom and return_location_custom. A pick-up location of another branch also needs a vehicle_class_id of that branch. |
| Vehicle class | vehicle_class_id. Add free_upgrade=1 to give the customer the new class at the price of the class they booked. The class must be available and belong to the booking's branch. |
| Extras | additional_charges[] with the full new selection: it replaces the current one, so leave a charge out to remove it. |
| Customer | customer_id of the other contact, in a call of its own. |
| Coupon | add_discount=1 with coupon_code, or remove_discount=1 with coupon_code. When the reservation has a manual discount and the API user's role can add one, resend manual_discount and manual_discount_is_percentage with add_discount=1: leaving them out removes it. |
additional_drivers with the full list of their contact IDs.See
POST /car-rental/reservations/{reservation_id}/update for the statuses that allow each change.Before you show a change as done, check
selected_additional_charges and applicable_discounts in the response.Errors to handle
"success": false, usually with HTTP 200: errors holds the messages per field and errors.error_message all of them, to show the customer (see Errors).On confirm, such a failure also uses up the
Idempotency-Key, so send a new key once the request is fixed.Idempotency-Key already used returns HTTP 422, with the ID of the reservation the first request created in errors.idempotency_value.When it holds an ID, the booking exists, so show it instead of an error.
When it is empty, look the reservation up before you retry (see Rate limits and idempotency).
Send them back to step 2, and confirm with a new
Idempotency-Key.Modified at 2026-10-29 14:10:30