Booking API
Hold a hotel room and pay later: how hotel holds work in the Partner API
By Idea Holiday team · Updated 26 Oct 2026 · 3 min read
Travellers often want a room secured while they confirm with their family or their company. A hold lets an agent do that without paying yet. This guide explains how holds work in the Idea Holiday Partner API and what they cost.
Which rooms can be held
Some rooms can be held: refundable rooms whose free cancellation ends far enough ahead. After prebook, the answer says whether the room can be held, and gives the last time to confirm it. Rates in search and hotel details carry the same flag.
The three steps
- Hold: send a booking request with the intent set to HOLD, and the guests. Nothing is paid. The booking is ON_HOLD, with a pay-by time. If the room cannot be held, you get a clear refusal.
- Confirm: before the pay-by time, send a confirm request with a new Idempotency-Key. Your wallet pays the price, the hotel issues the voucher and the booking becomes CONFIRMED. If the hotel is still confirming, you get a pending answer and read the booking again.
- Or release: let the room go yourself. The booking becomes CANCELLED and the hold is RELEASED.
What it costs
- A held room costs nothing and pays no API fee.
- When you confirm, the wallet pays the price and the API fee is charged once the hotel confirms.
- A hold that you do not confirm is released by Idea Holiday about an hour after the pay-by time, before the hotel's free cancellation ends. A released hold costs nothing.
When things go wrong
If the hotel cannot issue the voucher when you confirm, the payment is returned and the room stays held, so you can try again before the pay-by time. After the pay-by time, a confirm request is refused as expired.
Testing holds
Test keys hold demo rooms until 2 days before check-in, so you can build and check the whole flow without touching a real room.
Common questions
- Can every room be held?
- No. Only rooms flagged as holdable, which are refundable rooms whose free cancellation ends far enough ahead.
- Do I pay a fee if I release a hold?
- No. A released hold costs nothing and pays no API fee.
- Who pays when I confirm?
- Your agent wallet: your balance plus your credit limit.