API reference
The ChatBeds partner API, version 1. Twenty operations that let your app read a hotel's rooms and prices, book stays, and work with the guest's bill.
The partner API lets an app or a partner act for one hotel property: read its rooms, rates and policies, search what can be booked, create and change reservations, and post charges and payments to the guest's folio. Bookings made through it are priced, checked and alerted exactly like bookings made at the front desk.
Base URL
https://api.chatbeds.app/partner/v1Every path in this reference is relative to that address. All requests and responses are JSON over HTTPS.
Authentication
Send a credential in the Authorization header on every request.
| Credential | Looks like | Where it comes from | Header |
|---|---|---|---|
| Partner key | cbk_... | Made by the hotel on Settings, Partner API, or the key of your sandbox | Authorization: Bearer cbk_•••• or X-Api-Key: cbk_•••• |
| App access token | cbat_... | The OAuth flow when a hotel connects your app (1 hour; refresh it) | Authorization: Bearer cbat_•••• |
curl https://api.chatbeds.app/partner/v1/me \
-H "Authorization: Bearer cbk_••••"See Authentication for how to get each one, and OAuth for the app flow.
One property per credential
A key or token belongs to exactly one property. Anything outside it (another property's ID, a reservation or payment of another hotel) answers 404, never 403, so you cannot learn that it exists. Within its property a credential sees every booking, whoever made it: the front desk, WhatsApp, or another partner.
An app token can only do what the hotel allowed when it connected the app: each operation checks one scope, and a missing scope answers 403. Keys made by hand on Settings, Partner API have every scope.
Operations
The operation names are stable identifiers; GET /capabilities lists them.
| Operation | Method | Path | Scope |
|---|---|---|---|
identity.probe | GET | /me | none |
property.list | GET | /properties | property:read |
capability.describe | GET | /capabilities | none |
roomType.list | GET | /properties/{property_id}/room-types | rooms:read |
ratePlan.list | GET | /properties/{property_id}/rate-plans | rooms:read |
unit.list | GET | /properties/{property_id}/units | rooms:read |
extra.list | GET | /properties/{property_id}/extras | rooms:read |
policy.get | GET | /properties/{property_id}/policies | property:read |
offer.search | GET | /properties/{property_id}/offers | availability:read |
reservation.create | POST | /properties/{property_id}/reservations | reservations:write |
reservation.get | GET | /reservations/{reservation_id} | reservations:read |
reservation.search | GET | /properties/{property_id}/reservations | reservations:read |
reservation.modify | PATCH | /reservations/{reservation_id} | reservations:write |
reservation.cancel | POST | /reservations/{reservation_id}/cancel | reservations:write |
reservation.addExtra | POST | /reservations/{reservation_id}/extras | reservations:write |
folio.get | GET | /reservations/{reservation_id}/folio | folios:read |
folio.addCharge | POST | /reservations/{reservation_id}/folio/charges | folios:write |
folio.addPayment | POST | /reservations/{reservation_id}/folio/payments | folios:write |
payment.createLink | POST | /reservations/{reservation_id}/payment-link | payments:write |
payment.getStatus | GET | /payments/{payment_id} | folios:read |
Conventions
| What | Format |
|---|---|
| IDs | UUIDs, for example 19306340-c7cf-465a-93d3-0b7873a7e85d |
| Dates | The hotel's local dates, YYYY-MM-DD. arrival is the first night, departure the day the guest leaves |
| Times | ISO 8601 with an offset |
| Money | A number in the property's currency, to two places (180.0). The currency is on every priced object |
| Reservation status | confirmed, checked_in, checked_out, cancelled, no_show |
More on dates, money and headers in Conventions.
Writes and retries
Every POST and PATCH accepts an Idempotency-Key header (1 to 255 characters). The first answer to a key is kept for 24 hours; sending the same request again with the same key returns that answer, with Idempotent-Replayed: true, and changes nothing. Send one on every write, and always on reservation.create. See Idempotency.
Errors
Errors are JSON with a detail field: a sentence for most errors, a list of field problems for 422.
{
"detail": "Reservation not found"
}These can come from any operation:
| Status | When |
|---|---|
401 | No credential, or one that is wrong, revoked or expired |
403 | The app token lacks the operation's scope, or the hotel's ChatBeds account is not active |
404 | Not found, or not this credential's property |
422 | A field is missing or of the wrong shape (also: an Idempotency-Key reused for a different request) |
429 | More than 120 calls a minute for this credential. Wait for Retry-After seconds |
503 | The partner API is paused for this hotel. Retry after Retry-After seconds |
Each operation below lists the errors specific to it. The full list is in Errors; limits are in Rate limits.
In this section
Identity
Who the credential is, its property, and what the API supports.
Rooms and rates
Room types, rate plans, rooms, extras and the hotel's policies.
Availability
Priced offers for dates and guests.
Reservations
Book, read, search, change and cancel stays.
Folios and payments
The guest's bill, charges, payments and payment links.
Building something?