Read, change and cancel
Once a booking is made, you can read it, correct its client and guest
details, and cancel it in full or one room at a time. Every call finds the
booking either by our id (id) or by yours (ref_id). You only
ever see bookings your own agency made.
GET /booking
| Parameter | Required | |
|---|---|---|
id or ref_id |
one of them | Our booking id, or the ref_id you sent |
locale |
no | Language of the texts |
The booking carries:
- Status:
booking_status:REQUESTED,CREATED,APPROVED,CHECKIN,CHECKOUTorCANCELLED;payment_status:WAITING,FAILED,DEPOSIT_PAID,PARTIALLY_PAID,FULLY_PAIDorREFUNDED.
- The stay:
- dates,
total_amount,currency,notes; - the property and the client;
created_timestamp, when we created it, andbooking_timestamp. Abooking_timestampsent when booking is not stored today, so it equalscreated_timestamp.
- dates,
- Each room (
items):- the room and its rate plan, with the payment and cancellation policy the booking was made under;
- included extras, guests, and its own
idandref_id.beds_preferencesis empty for bookings made through the API: the preferences you send are not stored today.
payment_plan: the instalments, with their due dates, the payment methods for each, and whether each one is paid.
CANCELLED is final. A booking you cannot find (an unknown id, or one
another agency made) answers 404 with an empty body. An unknown or
unsupported locale falls back to English.
PATCH /booking
Corrects the details of a booking. The stay, the rooms, the prices and the status do not change.
Find the booking with id or ref_id in the query string, and send only
what you change:
{
"client": {
"first_name": "Ivan",
"last_name": "Petrov",
"email": "[email protected]",
"phone": "+359888123456"
},
"notes": "Arrival around 23:00",
"items": [
{
"ref_id": "AG-2026-00417-1",
"guests": [
{ "first_name": "Ivan", "last_name": "Petrov", "adult": true },
{ "first_name": "Nikola", "last_name": "Petrov", "adult": false, "non_adult_age": 7 }
]
}
]
}
clientreplaces the client as a whole: optional fields you leave out (nationality,company…) are cleared.notesreplaces the notes.itemslists only the rooms whose guests you change, each found by itsidor itsref_id. An item that matches no room of the booking is ignored. The new guests must still be a party the room takes, and the same party that was paid for: the number of adults and of children cannot change, and a child's age can change only within its age group (and not across the hotel's free age for young children). Names can always change.
A change is accepted only when all of these hold, and refused with error 17 otherwise (the message says which):
- the booking was made with
/booking/with-priceor/booking/request-with-price; - its status is
CREATED; - the hotel allows changing client and guest details on every rate plan in the booking;
- no room you change is cancelled;
- the body changes something (an empty body is refused: "Nothing to update.").
The message of a 17 starts with : (there is no fixed text before it).
PATCH /booking/cancel
Cancels the whole booking.
| Parameter | |
|---|---|
id or ref_id |
The booking |
The answer is the booking. Cancelling a booking that is already cancelled changes nothing and returns it. If the cancellation fails, the answer is error 11; an unknown booking answers 404 with an empty body.
PATCH /booking/cancel-item
Cancels one room and keeps the rest of the booking.
The answer is the booking. The cancelled room stays in items (a room has no
status of its own) and total_amount drops by its price; cancelling the last
room cancels the booking.
| Parameter | |
|---|---|
id or ref_id |
The booking, by our id or yours |
item_id or item_ref_id |
The room, by our id or yours |
The two pairs can be mixed (for example id with item_ref_id). A room
that is already cancelled changes nothing. A failure is error 11; a booking
or room we cannot find answers 404 with an empty body.
What a cancellation costs
Each rate plan carries its cancellation_policy (see
Content): a list of rules, each saying when it applies and
what it charges. The policy that applies is the one the booking was made
under. On the bookings you read (GET /booking) each rule of
an item's policy carries its description and penalty_ca: the penalty as
an amount and currency, or null where it cannot be worked out in advance.
Cancelling through the API applies the same policy as cancelling any other way. Check it before you cancel on your client's behalf.