Conventions
Base URL, request format, dates, money, IDs, statuses, booking sources and versioning.
Base URL
https://api.chatbeds.app/partner/v1All paths in these docs are relative to it. The OAuth endpoints live beside it, at https://api.chatbeds.app/oauth/token and https://api.chatbeds.app/oauth/revoke.
Requests and responses
- Send JSON bodies with
Content-Type: application/json. - Responses are JSON. A successful create answers
201; other successes answer200. - Errors are
{"detail": ...}. See Errors. - Writes accept an
Idempotency-Keyheader. See Idempotency.
Dates and times
| Kind | Format | Example |
|---|---|---|
| Dates (arrival, departure, nights) | YYYY-MM-DD, in the hotel's own time zone | 2026-10-31 |
| Timestamps | ISO 8601 with the offset | 2026-10-10T05:09:47.271659+00:00 |
| Times of day | HH:MM, hotel-local | "check_in_time": "14:00" |
departure is the day the guest leaves, so a stay from 2026-10-31 to 2026-11-02 is 2 nights. GET /properties returns the property's timezone and its today, the current date at the hotel. Use that, not your server's date, to decide what "tonight" means.
Money
Amounts are JSON numbers in the property's currency, to two decimal places, for example 180.0. The currency is on the property and on each offer and reservation ("currency": "USD"). There is no currency conversion.
IDs and references
| Field | What it is |
|---|---|
id | A UUID, for example a589df05-30ad-4ee5-9832-16ff6c2c1d0e. Use it in paths |
ref | A short booking reference the hotel and guest see, for example A589DF |
external_ref | Your reference for a booking, up to 100 characters. Unique per partner and property |
Search bookings by external_ref to find one you made, even if you lost its id.
Booking statuses
| Status | Meaning |
|---|---|
confirmed | Booked, guest not arrived yet |
checked_in | The guest is in the hotel |
checked_out | The stay is over |
cancelled | Cancelled under the hotel's policy |
no_show | The guest never arrived |
Payment statuses (from GET /payments/{id}) are PENDING, COMPLETED, EXPIRED, VOIDED and FAILED.
Booking sources
Every booking records where it came from in source. Bookings you make carry PARTNER:<slug>:
- with a private key, the slug is the key's partner name, for example
PARTNER:sandboxfor the sandbox key; - with an app, the slug is your app's slug, for example
PARTNER:booker.
Bookings made by the hotel itself carry other sources, such as MANUAL. You'll see them too, in searches and webhooks, so don't assume every booking is yours: check source or external_ref.
Versioning
The version is in the path: /partner/v1. GET /me and GET /capabilities also return "api_version": "1". Within v1, ChatBeds may add fields, operations and webhook events, so ignore fields you don't know. Breaking changes would come under a new path. See the changelog.
Building something?