Questa pagina non è ancora tradotta, quindi stai leggendo la versione inglese.
Build a booking channel
Sell a ChatBeds hotel's rooms in your own product, from showing prices to booking, changing and cancelling, without ever selling a room twice.
A booking channel is anything that sells rooms: an online travel agency, a travel app, a WhatsApp or web chatbot, a corporate booking tool. Bookings you make land in the hotel's ChatBeds like any other: on the tape chart, in the alerts, under the source PARTNER:<your app>.
Scopes you need: property:read, rooms:read, availability:read, reservations:read, reservations:write.
The flow
Learn the hotel
When a hotel connects, read what you need to show it:
| Call | Gives you | Cache for |
|---|---|---|
GET /properties | Name, address, timezone, currency | A day |
GET /capabilities | What this hotel supports (payment_links, extras...) | A day |
GET /properties/{id}/room-types | Names, sizes, photos, amenities | An hour |
GET /properties/{id}/policies | Check-in times, fees, cancellation terms | An hour |
Search offers
When a guest picks dates, ask for offers. One call returns every room type and rate plan that can actually be booked, priced by the hotel's own pricing engine.
curl "https://app.chatbeds.app/partner/v1/properties/$PROPERTY/offers?arrival=2026-10-31&departure=2026-11-02&adults=2" \
-H "Authorization: Bearer $TOKEN"{
"nights": 2,
"offers": [
{
"room_type": { "id": "da3b4c87-c1ca-4f13-8c90-066900f16d48", "name": "Standard", "max_occupancy": 2 },
"rate_plan": null,
"available": 6,
"currency": "USD",
"room_total": 180.0,
"total": 180.0
}
]
}Don't cache offers: prices and availability change with every booking. An empty list means nothing can be booked for those dates.
Show the terms
Before the guest commits, show the offer's total and the hotel's cancellation terms from policies. When a booking is cancelled, the hotel's policy decides the fee, and you can't waive it, so the guest should know it up front.
Book at the price you showed
Create the reservation with:
- the offer's
room_type_idandrate_plan_id(leave it out whenrate_planwasnull), - the offer's
totalasexpected_total, - your own booking ID as
external_ref, - an
Idempotency-Key, the same on every retry.
curl -X POST "https://app.chatbeds.app/partner/v1/properties/$PROPERTY/reservations" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: booking-BK-104233" \
-d '{
"room_type_id": "da3b4c87-c1ca-4f13-8c90-066900f16d48",
"arrival": "2026-10-31",
"departure": "2026-11-02",
"adults": 2,
"guest": {
"first_name": "Daniel",
"last_name": "Moore",
"email": "daniel.moore@example.com",
"phone": "+14155550123"
},
"external_ref": "BK-104233",
"notes": "Late arrival, around 23:00",
"expected_total": 180.0
}'201 returns the reservation. Store its id, and show the guest its ref (A589DF): it's what the hotel knows the booking by.
Handle the answers
| Answer | What happened | What to do |
|---|---|---|
201 | Booked | Confirm to the guest |
409 price changed | Nothing booked | Show the new total from detail, search again, and book with the new expected_total if the guest agrees |
409 duplicate external_ref | You booked this already | Search by external_ref and use that booking |
400 | The stay can't be booked as asked (for example, the room was just taken or the minimum stay isn't met) | Search again and offer what's left |
Timeout or 5xx | Unknown | Retry with the same Idempotency-Key. You get the booking, made once |
Changing a booking
Nights the guest keeps keep their price; new nights are priced at today's rates. Show the guest the new price before you save:
- Preview. Send only what changes to
PATCH /reservations/{id}?dry_run=true. Nothing is saved and no webhook goes out. The answer hasbefore,after(with each night's price) anddifference. - Show the guest
after.total. - Save at that price. Send the same body to
PATCH /reservations/{id}with"expected_total": <after.total>and anIdempotency-Key. A409"The price has changed" means nothing was saved: preview again. - Payment links. If the guest had an open card link that now asks too much, ChatBeds voids it and lists it in
voided_payment_links. Make a new link for what is owed. See Take payments.
Before arrival you can also change the room type or rate plan with room_type_id and rate_plan_id. Every night is priced again on them. The new room type must be free and fit the guests. Preview it the same way.
curl -X PATCH "https://app.chatbeds.app/partner/v1/reservations/$RESERVATION?dry_run=true" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "room_type_id": "<the Suite room type id>" }'Cancelling
- Quote.
GET /reservations/{id}/cancellation-quotegives thefeeandexplanationcancelling would give now, and what the guest would owe or be owed back. - Show the guest the fee and the explanation. The reservation's
cancellation_policyhas the same terms at any time. - Cancel.
POST /reservations/{id}/cancelwith areason. The response gives the fee the hotel's policy charged. The fee can rise oncefree_untilpasses, so quote just before.
If the guest had paid, refund_due is what the hotel owes back. ChatBeds does not refund by itself: the hotel makes the refund and records it. See Refunds.
Bookings made elsewhere
The hotel also sells rooms at the front desk, on its booking page, on WhatsApp and through other partners. Your offers already take all of those into account. To hear about changes to your bookings made by the hotel (a new room, a check-in, a cancellation), subscribe to webhooks and see Keep in sync. If you send payment links, turn on payment.completed instead of polling each payment; keep polling only as a fallback.
Checklist
-
expected_totalon every booking, and the409handled. -
Idempotency-Keyandexternal_refon every booking. - The cancellation terms shown before booking, and the quote before cancelling.
- Changes previewed and saved with
expected_total. - The hotel's
refshown to the guest. - Webhooks verified and handled.
- Tested end to end on the Sandbox Hotel: book, change, cancel.
Then work through the going-live checklist.
Stai creando qualcosa?