[AirHost API] Booking Engine Implementation FAQ

About Per-Night Room Rates When Creating a Reservation

When creating or updating a reservation via POST /stays (Create a Stay) or PUT /room_reservations/{id} (Update a Room Reservation), there is currently no field that lets you specify a per-night room rate for the reservation itself.

Please be aware of the following behavior when integrating your Booking Engine.

Topic	Description	Reason
booking_fee only accepts a total amount	`room_reservation.booking_fee` is a single number field representing the total accommodation charge for the entire stay. It cannot be broken down by night at creation time.	This is a current limitation of the Public API specification for reservation creation.
How the total is applied to each night	AirHost automatically splits the submitted total evenly across the number of nights to populate the reservation's per-night pricing. This averaged value is what's shown in the reservation order details, and is also the value used to calculate AirHost's automatic accommodation tax.	Because no per-night rate is submitted, the system has no other basis for populating a nightly breakdown.
charges is not a substitute for per-night rates	`charges[] (fee_type: booking_fee / dining_fee / cleaning_fee / cancellation_fee / other_fees)` is designed to record individual billable items (e.g. dining, cleaning, cancellation fees), not to specify nightly room rates. Even if you submit one charges entry per night with a date and amount, this data is only reflected in the transaction/invoice records — it is not written back into the reservation's own per-night pricing, and does not affect the automatic accommodation tax calculation.	charges was designed around AirHost-collected miscellaneous fees. Treating it as a substitute for nightly rates would affect other integrators who use charges for its intended purpose without submitting per-night data.
Impact on accommodation tax	Since AirHost's automatic accommodation tax calculation is based on the same per-night pricing derived from `booking_fee`, the tax amount will also be calculated using the averaged nightly rate, not the actual rate for each night — which may produce different results in municipalities that apply per-person, per-night tax brackets (e.g. Osaka).	The tax calculation reads from the same underlying per-night data as the reservation record.
Current workaround	If accurate per-night pricing and tax amounts are required, this currently needs to be handled manually: (1) manually correct the auto-generated accommodation tax amount, or (2) create the reservation manually via the AirHost UI instead of via the API.	There is no way to resolve this automatically via the API at present.

Important Notes on Prepayment and Automatic Payments for Bookings Created via the BE API

For prepayments for bookings created via the BE API, please process the payment through your own system.

Prepayment cannot be made for BE API bookings using AirHost's payment integration when the guest makes a booking.

Please also note that the settings under Channel Manager > Automatic Payments do not apply to bookings created via the BE API.

Using Prepayment During Pre-Check-in and Handling Refunds for Cancellations

If you would like guests to make a prepayment through AirHost's Pre-Check-in feature, you can use a payment solution integration.

Please note that if a booking is canceled after payment has been completed, the refund will not be processed automatically.

Please process the refund manually from the booking's Transaction Details screen.

For detailed refund instructions, please refer to this page.

[Check-in] Common Settings and Flow Settings | Pre-Check-in Flow