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://api.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://api.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
Send only what changes to PATCH /reservations/{id}. Nights the guest keeps keep their price; new nights are priced at today's rates. There is no price check on a change, so show the guest the new total from the response.
To change the room type or rate plan, cancel and book again.
Cancelling
POST /reservations/{id}/cancel with a reason. The response gives the fee the hotel's policy charged. If the guest had paid, a negative balance is what the hotel owes back; the hotel makes the refund.
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.
Checklist
-
expected_totalon every booking, and the409handled. -
Idempotency-Keyandexternal_refon every booking. - The cancellation terms shown before booking.
- 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.
Building something?