Skip to main content

[AirHost API] Booking Engine Implementation FAQ

J
Written by Joelly See Toh

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.


FAQ

Regarding Reservation Creation on Fully Booked Dates

Q. What response will be returned if a new reservation is created for a date that is already fully booked?

A. Even if a reservation is created for a date that is already fully booked, the reservation will still be saved and marked as Overlapped (overlapping reservation).

Therefore, instead of relying solely on the HTTP status code, you should also check the reservation status included in the API response.

Regarding Recovery After Exceeding the Feed Retention Period (7 Days)

Q. How can the system be recovered if the 7-day Feed retention period has been exceeded?

A. Past Feed events that are more than 7 days old cannot be restored.

Regarding API Access Rate Limit Adjustments

Q. Is it possible to increase the current API access limit of 120 requests per minute per partner?

A. Currently, we are unable to remove or increase this limit for individual integrations.

However, you can reduce the API request load by implementing the following measures:

  • Use a request queue to distribute API requests over time.

  • Expand the data scope retrieved in each query to reduce the total number of API requests.

  • Implement a retry mechanism when the rate limit is reached.

Regarding Reservations Created via API and Inventory / OTA Synchronization

Q. If a reservation is created or cancelled via API, will the inventory and OTA inventory be updated automatically?

A. Reservations created via API will be allocated against the available inventory in AirHost. Any changes to AirHost's inventory will be automatically synchronized with connected OTAs.

Additionally, reservation modifications and cancellations can be performed using the Update a Room Reservation endpoint. When a reservation is cancelled, the inventory will also be automatically released and synchronized with the connected OTAs.

Note: Updates to OTAs are not necessarily immediate. Depending on the OTA, synchronization may take a few minutes.

Did this answer your question?