ChatBedsडेवलपर्स
गाइड

इस पेज का अनुवाद अभी नहीं हुआ है, इसलिए आप अंग्रेज़ी संस्करण पढ़ रहे हैं।

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:

CallGives youCache for
GET /propertiesName, address, timezone, currencyA day
GET /capabilitiesWhat this hotel supports (payment_links, extras...)A day
GET /properties/{id}/room-typesNames, sizes, photos, amenitiesAn hour
GET /properties/{id}/policiesCheck-in times, fees, cancellation termsAn 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.

Request
curl "https://app.chatbeds.app/partner/v1/properties/$PROPERTY/offers?arrival=2026-10-31&departure=2026-11-02&adults=2" \
  -H "Authorization: Bearer $TOKEN"
Response (trimmed)
{
  "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_id and rate_plan_id (leave it out when rate_plan was null),
  • the offer's total as expected_total,
  • your own booking ID as external_ref,
  • an Idempotency-Key, the same on every retry.
Request
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

AnswerWhat happenedWhat to do
201BookedConfirm to the guest
409 price changedNothing bookedShow the new total from detail, search again, and book with the new expected_total if the guest agrees
409 duplicate external_refYou booked this alreadySearch by external_ref and use that booking
400The 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 5xxUnknownRetry 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:

  1. Preview. Send only what changes to PATCH /reservations/{id}?dry_run=true. Nothing is saved and no webhook goes out. The answer has before, after (with each night's price) and difference.
  2. Show the guest after.total.
  3. Save at that price. Send the same body to PATCH /reservations/{id} with "expected_total": <after.total> and an Idempotency-Key. A 409 "The price has changed" means nothing was saved: preview again.
  4. 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.

Request
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

  1. Quote. GET /reservations/{id}/cancellation-quote gives the fee and explanation cancelling would give now, and what the guest would owe or be owed back.
  2. Show the guest the fee and the explanation. The reservation's cancellation_policy has the same terms at any time.
  3. Cancel. POST /reservations/{id}/cancel with a reason. The response gives the fee the hotel's policy charged. The fee can rise once free_until passes, 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_total on every booking, and the 409 handled.
  • Idempotency-Key and external_ref on every booking.
  • The cancellation terms shown before booking, and the quote before cancelling.
  • Changes previewed and saved with expected_total.
  • The hotel's ref shown 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.

कुछ बना रहे हैं?

इस पेज पर