Guide: bill tolls and fines

Use this guide to bill tolls, traffic fines and similar costs to the customer who had the vehicle at that moment.
For each toll you find the reservation, add the toll to it, and optionally charge the customer's saved card and attach the toll invoice.
For fines, one call does the matching for you.

Step 1 - Map plates to vehicles

GET /fleets/vehicles returns your vehicles with their id and plate.
Load it once a day and keep a plate-to-ID map.
Send show_inactive=1 as well, so that vehicles sold or retired since the toll still match.

Step 2 - Find the reservation

Ask for the reservation that had the vehicle at the time of the toll:

Parameter	Meaning
`on_date`	When the toll happened, `YYYY-MM-DD HH:mm`, in the API user's time zone (see Dates, time zones and money). Convert the toll agency's time first.
`vehicle_id`	The HQ vehicle ID.
`vehicle_plate`	The exact plate, instead of `vehicle_id`.
`vehicle_plate_state`	The US state of the plate, together with `vehicle_plate`.
`toll_tag_number`	The toll tag, instead of the plate. Send it only when toll tags are set up in your account; otherwise it is ignored and only `on_date` applies, which matches every rental out at that moment, so send `vehicle_id` or `vehicle_plate` instead.

The match uses every vehicle assignment of the reservation, including replaced vehicles, so it finds the reservation that had this vehicle at that exact moment.
The reservations are in data:

One reservation: bill it.

None: the vehicle was not on rent at that moment.
Check the time zone of on_date; if there is still no match, the toll does not belong to a customer.

Several: the vehicle changed hands around that time.
Compare the assignment dates in reservation_vehicle_information with the toll time.

The match does not look at the reservation status, so check status before you bill, for example that it is rental or completed.

Step 3 - Add the toll to the reservation

Field	Meaning
`vehicle_id`	Required. A vehicle assigned to this reservation; any other vehicle returns `"success": false`.
`charge_date`	Required. When the toll happened, `YYYY-MM-DD HH:mm`, in the API user's time zone, like `on_date`.
`charge_amount`	Required. The amount, with a dot as the decimal separator.
`label`	The name of the charge, for example the toll road and plaza.
`notes`	Notes, for example the toll agency's transaction ID.

HQ adds the charge and recalculates the reservation totals.
The response has data.reservation and data.external_charges, every external charge of the reservation with its id.

There is no duplicate check, so posting the same toll twice bills it twice.
Keep the toll transaction IDs you have already posted, for example in notes and in your own database.

If the reservation includes the additional charge your account uses for unlimited tolls, tolls added this way are kept on the reservation but not added to its total.

Step 4 - Charge the customer's saved card (optional)

POST /car-rental/reservations/{reservation_id}/payments/charge-credit-card with amount, the charge_amount from step 3.
Skip reservations with unlimited tolls, whose total does not include the toll.
To charge a fee, include it in charge_amount in step 3 or post it as its own external charge, so the reservation total matches what you charge.
Read data.result in the response, which is HTTP 200 even when the card was declined; add send_payment_request=1 to email the customer a payment link when no saved card works.
See Guide: take payments for the other options.

Step 5 - Attach the toll invoice (optional)

POST /files/upload as multipart form data:

Field	Value
`file`	The PDF.
`filename`	Required. A name for the file, for example `toll-2026-05-23.pdf`.
`item_type`	`car_rental.reservation_external_charges`
`item_id`	The external charge `id` from step 3.

Fines

For traffic and parking fines, POST /car-rental/fines stores the fine and bills it in one step:

Field	Meaning
`fine_number`	Required. The fine or ticket number.
`fine_type`	Required. For example `Parking` or `Speeding`.
`amount`	Required. The amount of the fine.
`date`	Required. When the offense happened, `YYYY-MM-DD HH:mm`, in the API user's time zone.
`vehicle_plate`	Required. The plate of a vehicle in HQ.
`fine_file`	Optional. The scan of the fine, sent as multipart form data.
`paid_to_authority`	Optional. `1` when you already paid the authority.
`notes`	Optional.

HQ looks for the rental or completed reservation that had the vehicle at that moment and adds the fine to it as an external charge, with the fine's file attached.
Use an API user set to UTC for fines, and send date in UTC.
The response returns the fine with its reservation_id, which is null when no reservation matched.
GET /car-rental/fines lists the fines and accepts vehicle_plate and reservation_id.
Like tolls, fines have no duplicate check, so look the fine up in this list before you retry a POST.

Fines are saved in the form your account uses for fines, so your HQ administrator must set up the fines form and its fields in the car rental settings before you use these endpoints.

Step 1 - Map plates to vehicles#

Step 2 - Find the reservation#

Step 3 - Add the toll to the reservation#

Step 4 - Charge the customer's saved card (optional)#