ChatBedsDéveloppeurs
Référence de l’API

Cette page n’est pas encore traduite : vous lisez la version anglaise.

Reservations

Book stays, read and search them, preview and make changes, quote and cancel under the hotel's policy, and add extras.

A reservation made through the API is a normal ChatBeds booking: it is priced by the hotel's pricing engine, shows on the hotel's tape chart, alerts the staff, and carries the source PARTNER:<partner> plus your own external_ref. It is booked as pay at the hotel; take money with a payment link or record a payment you took yourself.

The reservation object

Every operation on this page returns a reservation in this shape (search returns a list of them).

FieldTypeMeaning
iduuidStore it: every later call uses it
refstringThe short reference the hotel sees and the guest is told, such as A589DF
property_iduuid
statusstringconfirmed, checked_in, checked_out, cancelled or no_show. A booking made elsewhere at the hotel can also be pending; it holds its room like a confirmed one
sourcestringWho made it: PARTNER:<partner> for you; CHANNEX:<site> for a booking site through the channel manager; other values for the front desk, the booking page, other partners
external_refstring or nullYour reference, as you sent it
arrival, departuredateFirst night; day of departure
nights, adults, childreninteger
guestobjectfirst_name, last_name, email, phone
room_typeobject or null{"id", "name"}
unitobject or null{"id", "name"} once a room is assigned; null until the hotel assigns one
rate_planobject or null{"id", "name"}, or null for the room type's own rate
currencystring
totalnumberEverything charged on the folio (room, extras, fees, tax, charges)
paidnumberPayments received
balancenumbertotal minus paid. Negative means the hotel owes the guest a refund
refund_duenumberWhat was paid beyond the total (after a cancellation or a cheaper change). The hotel owes it back. 0 otherwise. See Refunds
payment_linksarrayCard payment links that can still be paid, as payment objects. Empty when none is open
cancellation_policyobject or nullThe policy this booking is under, and what cancelling now would cost. null when the booking is not confirmed or pending. See below
depositobject or nullThe hotel's deposit rule for this booking, or null: amount asked at booking (due_on), the rest by balance_due_on. due_now is what should be paid by today; owing_now what is still unpaid of it. ChatBeds never cancels a booking for an unpaid deposit
cancellationobject or nullWhen cancelled: {"fee", "reason", "cancelled_at"}
created_at, updated_atdatetime

The cancellation policy

cancellation_policy tells you, at any time, what the guest would pay to cancel now.

FieldTypeMeaning
id, nameuuid, stringThe policy. null when the hotel has no policy
free_cancellation_hoursinteger or nullHow many hours before arrival the guest can cancel for free
charge_typestringNIGHTS, PERCENTAGE, or NONE when the hotel has no policy
charge_valuenumberNights charged, or the percent of the room price
free_untildatetime or nullWhen free cancellation ends
free_nowbooleantrue if cancelling now costs nothing
fee_nownumberThe fee if cancelled now
explanationstringOne sentence you can show the guest

The policy is the rate plan's own if it has one. Otherwise it is the one the booking was made under (on the hotel's booking page), else the hotel's default. A non-refundable rate plan without a policy shows PERCENTAGE with charge_value: 100.

cancellation_policy
{
  "id": "5d0c1f7e-2a43-4b8e-9f3a-6f1f6d0c2b11",
  "name": "Flexible",
  "free_cancellation_hours": 48,
  "charge_type": "NIGHTS",
  "charge_value": 1.0,
  "free_until": "2026-10-29T14:00:00+00:00",
  "free_now": true,
  "fee_now": 0.0,
  "explanation": "Free to cancel until 29 Oct 2026, 14:00 (Flexible)."
}

The fee can go up once free_until passes. For the full figures before cancelling, use Get a cancellation quote.

Create a reservation

POST/properties/{property_id}/reservations
Scope reservations:writeOperation reservation.create

Books a stay and returns it with 201 Created. Send the offer's total as expected_total, your own booking ID as external_ref, and an Idempotency-Key header.

Body

property_id uuid (path)required
The property.
room_type_id uuid
The room type to book, from the offer. Required unless you give unit_id.
unit_id uuid
A specific room. With room_type_id, it must be of that type. Without it, the hotel assigns a room later.
rate_plan_id uuid
The offer's rate_plan.id. Leave it out for the room type's own rate (rate_plan: null).
arrival daterequired
The first night, YYYY-MM-DD.
departure daterequired
The day the guest leaves.
adults integer
1 to 20. Default 1.
children integer
0 to 20. Default 0.
child_ages integer[]
Each child's age, 0 to 17, as many as children. Under 2: an infant, not counted against the room's size. Children are priced by the room's age bands. The guests must fit the room (400 otherwise) and the hotel's children policy.
cots integer
Cots asked for, up to the room type's cots. Default 0.
extra_beds integer
Extra beds, up to the room type's extra_beds; each adds a place and costs extra_bed_price a night. Default 0.
guest objectrequired
The lead guest. A new guest record is made for each booking; it is never matched to an existing guest by email.
guest.first_name stringrequired
1 to 100 characters.
guest.last_name string
Up to 100 characters. Default empty.
guest.email string
Up to 255 characters.
guest.phone string
Up to 50 characters. Include the country code, for example +14155550123.
extras array
Up to 20 items, each {"extra_id": uuid, "quantity": 1-99} (quantity defaults to 1). See extras.
external_ref string
Your reference for the booking. Up to 100 characters: letters, digits and . _ : - /. Unique per partner and property: a second booking with the same value is refused.
notes string
Up to 1,000 characters, shown to the hotel staff (arrival time, requests).
promo_code string
The promo code the offer was priced with. The booking is made at the lower price (and refused with 400 saying why if the code no longer applies, for example used up).
rate_code string
The code of a private (corporate) rate plan. Needed to book that rate_plan_id; the stay is linked to the company the rate is for.
expected_total number
The total you showed the guest, 0 to 99,999,999.99. If the price is now different (by more than half a cent), nothing is booked and the answer is 409 with the new total. Strongly recommended.
Header
Idempotency-Key1 to 255 characters. Strongly recommended: use one per booking attempt, for example your booking ID, and send the same key on every retry. See Idempotency

Example

Request
curl -X POST "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/reservations" \
  -H "Authorization: Bearer cbk_••••" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: b2f1c9e4-booking-BK-104233" \
  -d '{
    "room_type_id": "da3b4c87-c1ca-4f13-8c90-066900f16d48",
    "arrival": "2026-10-31",
    "departure": "2026-11-02",
    "adults": 2,
    "children": 0,
    "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 Created
{
  "reservation": {
    "id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
    "ref": "A589DF",
    "property_id": "19306340-c7cf-465a-93d3-0b7873a7e85d",
    "status": "confirmed",
    "source": "PARTNER:sandbox",
    "external_ref": "BK-104233",
    "arrival": "2026-10-31",
    "departure": "2026-11-02",
    "nights": 2,
    "adults": 2,
    "children": 0,
    "guest": {
      "first_name": "Daniel",
      "last_name": "Moore",
      "email": "daniel.moore@example.com",
      "phone": "+14155550123"
    },
    "room_type": {
      "id": "da3b4c87-c1ca-4f13-8c90-066900f16d48",
      "name": "Standard"
    },
    "unit": null,
    "rate_plan": null,
    "currency": "USD",
    "total": 180.0,
    "paid": 0.0,
    "balance": 180.0,
    "refund_due": 0.0,
    "payment_links": [],
    "cancellation_policy": {"id": null, "name": null, "free_cancellation_hours": null, "charge_type": "NONE", "charge_value": 0.0, "free_until": null, "free_now": true, "fee_now": 0.0, "explanation": "This hotel has no cancellation policy, so nothing is charged."},
    "deposit": {"amount": 54.0, "due_on": "2026-10-10", "balance_due_on": "2026-11-03", "due_now": 54.0, "owing_now": 54.0, "overdue": false},
    "cancellation": null,
    "created_at": "2026-10-10T05:09:47.271659+00:00",
    "updated_at": "2026-10-10T05:09:47+00:00"
  }
}

Sending the same request again with the same Idempotency-Key returns the same 201 body with the header Idempotent-Replayed: true, and books nothing.

Errors

StatusdetailWhat to do
409The price has changed: the total is now USD 180.00.Search offers again and show the guest the new price. Nothing was booked
409A booking with external_ref BK-104233 already exists (a589df05-30ad-4ee5-9832-16ff6c2c1d0e).This booking was already made: use the ID in the message, or reservation.search by external_ref
409No Standard room is available for the selected dates.Sold out since you searched. Search again
409Unit is already booked for the selected dates.The unit_id you chose is taken. Book by room type instead
409The hotel does not accept this booking. Ask the guest to contact the hotel.The hotel has marked this guest (by email or phone). Don't retry; the guest contacts the hotel
409Standard is not on sale.The room type was switched off
409A request with this Idempotency-Key is already being processed.Two requests with the same key at once. Wait and retry with the same key
400Give room_type_id (and unit_id to choose the room).Neither was sent
400That unit is not of that room type.unit_id and room_type_id disagree
400external_ref: letters, digits and . _ : - / only, up to 100 characters.Fix the reference
400Standard is closed to new bookings on ..., Stays arriving on ... need at least ..., ... closed to arrivals on ..., ... closed to departures on ...The hotel's stay rules. Offers leave these out
400That rate plan belongs to another property.Wrong rate_plan_id
400Idempotency-Key must be 1 to 255 characters.
404Room type not found, Unit not found, Extra not found, Property not foundAn ID that is not this property's
422A list of field problemsA required field is missing or out of range, or the Idempotency-Key was used for a different request
422 Unprocessable Entity
{
  "detail": [
    {
      "loc": [
        "body",
        "departure"
      ],
      "msg": "Field required",
      "type": "missing"
    },
    {
      "loc": [
        "body",
        "guest"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Get a reservation

GET/reservations/{reservation_id}
Scope reservations:readOperation reservation.get

Returns one reservation at the property, whoever made it. Use it to refresh your copy when a webhook arrives.

Parameters

reservation_id uuid (path)required
The reservation's id.

Example

Request
curl -X GET "https://app.chatbeds.app/partner/v1/reservations/a589df05-30ad-4ee5-9832-16ff6c2c1d0e" \
  -H "Authorization: Bearer cbk_••••"
200 OK
{
  "reservation": {
    "id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
    "ref": "A589DF",
    "property_id": "19306340-c7cf-465a-93d3-0b7873a7e85d",
    "status": "confirmed",
    "source": "PARTNER:sandbox",
    "external_ref": "BK-104233",
    "arrival": "2026-10-31",
    "departure": "2026-11-02",
    "nights": 2,
    "adults": 2,
    "children": 0,
    "guest": {
      "first_name": "Daniel",
      "last_name": "Moore",
      "email": "daniel.moore@example.com",
      "phone": "+14155550123"
    },
    "room_type": {
      "id": "da3b4c87-c1ca-4f13-8c90-066900f16d48",
      "name": "Standard"
    },
    "unit": null,
    "rate_plan": null,
    "currency": "USD",
    "total": 180.0,
    "paid": 0.0,
    "balance": 180.0,
    "refund_due": 0.0,
    "payment_links": [],
    "cancellation_policy": {"id": null, "name": null, "free_cancellation_hours": null, "charge_type": "NONE", "charge_value": 0.0, "free_until": null, "free_now": true, "fee_now": 0.0, "explanation": "This hotel has no cancellation policy, so nothing is charged."},
    "cancellation": null,
    "created_at": "2026-10-10T05:09:47.271659+00:00",
    "updated_at": "2026-10-10T05:09:47+00:00"
  }
}

Errors

StatusdetailWhen
403The app token lacks reservations:read
404Reservation not foundNo such reservation at this property

Search reservations

GET/properties/{property_id}/reservations
Scope reservations:readOperation reservation.search

Finds reservations at the property by exact arrival date, exact departure date, guest last name or your external_ref. Give at least one of those four; status and limit only narrow the result. Results are sorted by arrival, then by when they were made.

Parameters

property_id uuid (path)required
The property.
arrival date (query)
Reservations arriving on exactly this date.
departure date (query)
Reservations leaving on exactly this date.
lastName string (query)
The guest's last name, matched in full and ignoring case. Up to 100 characters. last_name also works.
external_ref string (query)
Your reference, matched exactly. Up to 100 characters.
status string (query)
confirmed, checked_in, checked_out, cancelled or no_show.
limit integer (query)
1 to 100. Default 50.

Example

Request
curl -X GET "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/reservations?external_ref=BK-104233" \
  -H "Authorization: Bearer cbk_••••"
200 OK
{
  "reservations": [
    {
      "id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
      "ref": "A589DF",
      "property_id": "19306340-c7cf-465a-93d3-0b7873a7e85d",
      "status": "confirmed",
      "source": "PARTNER:sandbox",
      "external_ref": "BK-104233",
      "arrival": "2026-10-31",
      "departure": "2026-11-02",
      "nights": 2,
      "adults": 2,
      "children": 0,
      "guest": {
        "first_name": "Daniel",
        "last_name": "Moore",
        "email": "daniel.moore@example.com",
        "phone": "+14155550123"
      },
      "room_type": {
        "id": "da3b4c87-c1ca-4f13-8c90-066900f16d48",
        "name": "Standard"
      },
      "unit": null,
      "rate_plan": null,
      "currency": "USD",
      "total": 180.0,
      "paid": 0.0,
      "balance": 180.0,
      "refund_due": 0.0,
      "payment_links": [],
      "cancellation_policy": {"id": null, "name": null, "free_cancellation_hours": null, "charge_type": "NONE", "charge_value": 0.0, "free_until": null, "free_now": true, "fee_now": 0.0, "explanation": "This hotel has no cancellation policy, so nothing is charged."},
      "cancellation": null,
      "created_at": "2026-10-10T05:09:47.271659+00:00",
      "updated_at": "2026-10-10T05:09:47+00:00"
    }
  ]
}

No ranges, no pages

arrival and departure match one date, not a range, and there is no next page. To cover a period, search day by day; if a day returns limit results, narrow it with status. See Keep bookings in sync.

Errors

StatusdetailWhen
400Search by arrival, departure, last_name or external_ref.None of the four was given
400Unknown status. Use confirmed, checked_in, checked_out, cancelled or no_show.
403The app token lacks reservations:read
404Property not found
422A date that is not a date, or limit out of range

Modify a reservation

PATCH/reservations/{reservation_id}
Scope reservations:writeOperation reservation.modify

Changes the dates, the number of guests, the guest's details, the notes, and (before arrival) the room type and rate plan. Send only the fields that change.

To show the guest the new price first, preview the change with ?dry_run=true, then save it with that total as expected_total.

Body

reservation_id uuid (path)required
The reservation.
dry_run boolean (query)
true to preview the change and save nothing. Default false.
room_type_id uuid
Move the booking to another room type. Only before arrival (confirmed or pending). See Changing the room type or rate plan.
rate_plan_id uuid
Move the booking to another rate plan. Only before arrival.
expected_total number
The new total you showed the guest, usually the preview's after.total. If the saved total would be different (by more than half a cent), nothing is saved and the answer is 409 with the new total. Recommended.
arrival date
New first night.
departure date
New day of departure.
adults integer
1 to 20.
children integer
0 to 20.
child_ages integer[]
Each child's age, as many as children. The nights' price for more guests follows the new guests.
cots integer
Cots.
extra_beds integer
Extra beds.
guest object
Any of first_name (1 to 100 characters), last_name (up to 100), email (up to 255), phone (up to 50). Fields you leave out are kept.
notes string
Up to 1,000 characters. Replaces the notes.

How the price follows a change:

ChangeEffect on the folio
Nights keptKeep the price they were booked at
New nightsPriced now, at today's rates
Nights droppedCome off the folio
Extras sold per nightFollow the new number of nights
Extras sold per personFollow the new number of guests
A new room type or rate planEvery night is priced again, as a new booking would be
A booking with a price agreed by handKeeps its nightly rate for every night

The room (or, for a booking without a room yet, the room type) must be free on the new nights, and the rate plan's minimum stay still applies.

Changing the room type or rate plan

  • Only before arrival: the booking must be confirmed or pending. Otherwise 409.
  • Every night is priced again on the new room type and rate plan, as a new booking would be. The rate plan's rules apply (minimum stay, closed dates).
  • The new room type must be free for the dates (409 if not), and the guests must fit it (400 if not).
  • The assigned room is kept if it is of the new type. Otherwise unit becomes null and the hotel assigns a room.
  • A booking with a price the hotel agreed by hand is refused (409). Ask the hotel to change it.
  • Dates and guests sent in the same request are applied first. The new room type is then priced for the stay as it now is.

The response also has voided_payment_links. When the open card links of the booking together ask more than is now owed (a shorter stay, say), they are all voided, at Stripe too, and listed here. Make one new payment link for what is owed. Links that still fit stay open, and the list is empty.

Example

Request
curl -X PATCH "https://app.chatbeds.app/partner/v1/reservations/a589df05-30ad-4ee5-9832-16ff6c2c1d0e" \
  -H "Authorization: Bearer cbk_••••" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: BK-104233-change-1" \
  -d '{
    "adults": 2,
    "notes": "Late arrival, around 23:30; needs a cot"
  }'
200 OK
{
  "reservation": {
    "id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
    "ref": "A589DF",
    "property_id": "19306340-c7cf-465a-93d3-0b7873a7e85d",
    "status": "confirmed",
    "source": "PARTNER:sandbox",
    "external_ref": "BK-104233",
    "arrival": "2026-10-31",
    "departure": "2026-11-02",
    "nights": 2,
    "adults": 2,
    "children": 0,
    "guest": {
      "first_name": "Daniel",
      "last_name": "Moore",
      "email": "daniel.moore@example.com",
      "phone": "+14155550123"
    },
    "room_type": {
      "id": "da3b4c87-c1ca-4f13-8c90-066900f16d48",
      "name": "Standard"
    },
    "unit": null,
    "rate_plan": null,
    "currency": "USD",
    "total": 180.0,
    "paid": 0.0,
    "balance": 180.0,
    "refund_due": 0.0,
    "payment_links": [],
    "cancellation_policy": {"id": null, "name": null, "free_cancellation_hours": null, "charge_type": "NONE", "charge_value": 0.0, "free_until": null, "free_now": true, "fee_now": 0.0, "explanation": "This hotel has no cancellation policy, so nothing is charged."},
    "cancellation": null,
    "created_at": "2026-10-10T05:09:47.271659+00:00",
    "updated_at": "2026-10-10T05:09:47+00:00"
  },
  "voided_payment_links": []
}

Notes are not part of the reservation object; the hotel sees them on the booking.

Errors

StatusdetailWhen
400Nothing to change.The body had no field to change
400Check-out date must be after check-in date.
400... needs a stay of at least ... nights. ...The new stay is shorter than the rate plan allows
400Suite sleeps 2: 3 guests is too many. ..., Suite takes at most 2 adults.The guests don't fit the new room type
409The price has changed: the new total is USD 450.00. Preview the change again.expected_total differs from the new total. Nothing was saved
409The room type and rate plan can be changed only before arrival.room_type_id or rate_plan_id on a booking that is not confirmed or pending
409This booking has a price agreed with the hotel. Ask the hotel to change its room.The hotel set the price by hand
409Suite is not on sale.The room type or rate plan was switched off
409A reservation with status 'cancelled' can only have its guest details and notes changed.Dates or guests on a cancelled or checked-out booking
409The guest has already arrived, so the arrival date cannot change.The guest is checked in
409No ... room is available for the selected dates., Unit is already booked for the selected dates.The new nights, or the new room type, are not free
403The app token lacks reservations:write
404Reservation not found, Room type not found, Rate plan not foundAn ID that is not this property's

Preview a change

PATCH/reservations/{reservation_id}?dry_run=true
Scope reservations:writeOperation reservation.previewChange

Prices a change exactly as saving it would, and saves nothing. Send the same body as Modify a reservation. Nights kept keep their price, new nights are at today's rate, and a new room type or rate plan prices every night again.

A preview sends no webhook and touches no payment link. It is not stored for Idempotency-Key, so you can preview as often as you like. expected_total is ignored here.

Example

Request
curl -X PATCH "https://app.chatbeds.app/partner/v1/reservations/a589df05-30ad-4ee5-9832-16ff6c2c1d0e?dry_run=true" \
  -H "Authorization: Bearer cbk_••••" \
  -H "Content-Type: application/json" \
  -d '{"departure": "2026-11-03"}'

Here the rate went up from USD 90 to USD 100 after booking. The two nights kept keep USD 90; the new night is at today's USD 100.

200 OK
{
  "preview": {
    "before": {
      "total": 180.0,
      "paid": 0.0,
      "balance": 180.0,
      "refund_due": 0.0,
      "currency": "USD",
      "arrival": "2026-10-31",
      "departure": "2026-11-02",
      "room_type": { "id": "da3b4c87-c1ca-4f13-8c90-066900f16d48", "name": "Standard" },
      "rate_plan": null,
      "nights": [
        { "date": "2026-10-31", "amount": 90.0 },
        { "date": "2026-11-01", "amount": 90.0 }
      ]
    },
    "after": {
      "total": 280.0,
      "paid": 0.0,
      "balance": 280.0,
      "refund_due": 0.0,
      "currency": "USD",
      "arrival": "2026-10-31",
      "departure": "2026-11-03",
      "room_type": { "id": "da3b4c87-c1ca-4f13-8c90-066900f16d48", "name": "Standard" },
      "rate_plan": null,
      "nights": [
        { "date": "2026-10-31", "amount": 90.0 },
        { "date": "2026-11-01", "amount": 90.0 },
        { "date": "2026-11-02", "amount": 100.0 }
      ]
    },
    "difference": 100.0,
    "dry_run": true
  }
}
FieldMeaning
before, afterThe booking now, and as it would be: total, paid, balance, refund_due, currency, arrival, departure, room_type, rate_plan and each night's amount
differenceafter.total minus before.total. Negative when the change is cheaper
dry_runAlways true

Show the guest after.total. If they agree, send the same body without dry_run and with "expected_total": 280.0. If the price moved in between, you get 409 and nothing is saved: preview again.

Errors

The same as Modify a reservation, without the price check (expected_total is ignored) and the Idempotency-Key errors.

Get a cancellation quote

GET/reservations/{reservation_id}/cancellation-quote
Scope reservations:readOperation reservation.cancellationQuote

What cancelling would cost now, without cancelling. The fee and explanation are exactly what Cancel a reservation would give at that moment. Show them to the guest before they confirm.

The fee can rise once free_until passes. Quote again just before you cancel.

Parameters

reservation_id uuid (path)required
The reservation.

Example

Request
curl -X GET "https://app.chatbeds.app/partner/v1/reservations/a589df05-30ad-4ee5-9832-16ff6c2c1d0e/cancellation-quote" \
  -H "Authorization: Bearer cbk_••••"

A booking on a non-refundable rate plan whose policy charges 100% of the room price:

200 OK
{
  "quote": {
    "reservation_id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
    "currency": "USD",
    "fee": 180.0,
    "free": false,
    "free_until": "2026-10-01T14:00:00+00:00",
    "explanation": "Free cancellation ended 01 Oct 2026, 14:00. Strict charges 100% of the room price.",
    "policy": {
      "id": "8c2e0a51-7d3b-4f6e-a1c9-2b5d4e6f7a80",
      "name": "Strict",
      "free_cancellation_hours": 720,
      "charge_type": "PERCENTAGE",
      "charge_value": 100.0,
      "free_until": "2026-10-01T14:00:00+00:00",
      "free_now": false,
      "fee_now": 180.0,
      "explanation": "Free cancellation ended 01 Oct 2026, 14:00. Strict charges 100% of the room price."
    },
    "refundable": false,
    "paid": 0.0,
    "balance_after": 180.0,
    "refund_due_after": 0.0,
    "quoted_at": "2026-10-19T09:12:30.418205+00:00"
  }
}
FieldMeaning
feeWhat cancelling now charges
freetrue if cancelling now costs nothing
free_untilWhen free cancellation ends, or null
explanationOne sentence to show the guest
policyThe cancellation policy
refundabletrue when the fee is less than the room price
paidWhat the guest has paid so far
balance_afterWhat the guest would still owe after cancelling
refund_due_afterWhat the hotel would owe back after cancelling
quoted_atWhen this quote was made

Errors

StatusdetailWhen
409A booking that is cancelled cannot be cancelled. (or checked in, checked out, no show)Only confirmed and pending bookings can be quoted
403The app token lacks reservations:read
404Reservation not found

Cancel a reservation

POST/reservations/{reservation_id}/cancel
Scope reservations:writeOperation reservation.cancel

Cancels under the hotel's own cancellation policy. The fee the policy gives goes on the folio and the stay's charges come off; you cannot waive or change the fee. Payments already taken stay on the folio, so a negative balance (and refund_due) is a refund the hotel owes the guest. ChatBeds does not refund by itself; see Refunds. The response includes the policy's explanation and the fee it charged.

To show the fee before cancelling, get a cancellation quote. Cancelling also voids any card payment link still open on the booking.

Cancelling a reservation that is already cancelled changes nothing and answers with the reservation as it is, with policy: null. A no-show is also already cancelled.

Body

reservation_id uuid (path)required
The reservation.
reason string
Up to 255 characters, shown to the hotel. The body is optional.

Example

Request
curl -X POST "https://app.chatbeds.app/partner/v1/reservations/a589df05-30ad-4ee5-9832-16ff6c2c1d0e/cancel" \
  -H "Authorization: Bearer cbk_••••" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: BK-104233-cancel" \
  -d '{"reason": "Guest changed plans"}'

In this recorded run, a USD 100 payment had been recorded before cancelling. The sandbox hotel has no cancellation policy, so the fee is 0, the charges come off, and the USD 100 remains as a refund due (balance: -100.0, refund_due: 100.0). A cancelled booking has cancellation_policy: null.

200 OK
{
  "reservation": {
    "id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e",
    "ref": "A589DF",
    "property_id": "19306340-c7cf-465a-93d3-0b7873a7e85d",
    "status": "cancelled",
    "source": "PARTNER:sandbox",
    "external_ref": "BK-104233",
    "arrival": "2026-10-31",
    "departure": "2026-11-02",
    "nights": 2,
    "adults": 2,
    "children": 0,
    "guest": {
      "first_name": "Daniel",
      "last_name": "Moore",
      "email": "daniel.moore@example.com",
      "phone": "+14155550123"
    },
    "room_type": {
      "id": "da3b4c87-c1ca-4f13-8c90-066900f16d48",
      "name": "Standard"
    },
    "unit": null,
    "rate_plan": null,
    "currency": "USD",
    "total": 0.0,
    "paid": 100.0,
    "balance": -100.0,
    "refund_due": 100.0,
    "payment_links": [],
    "cancellation_policy": null,
    "cancellation": {
      "fee": 0.0,
      "reason": "Guest changed plans",
      "cancelled_at": "2026-10-10T05:09:47.509902+00:00"
    },
    "created_at": "2026-10-10T05:09:47.271659+00:00",
    "updated_at": "2026-10-10T05:09:47+00:00"
  },
  "policy": {
    "explanation": "This hotel has no cancellation policy, so nothing is charged.",
    "fee": 0.0
  }
}

Errors

StatusdetailWhen
409The guest is checked in. Check them out instead of cancelling.
409This stay is already finished and cannot be cancelled.The guest has checked out
403The app token lacks reservations:write
404Reservation not found

Add an extra

POST/reservations/{reservation_id}/extras
Scope reservations:writeOperation reservation.addExtra

Adds an extra (breakfast, airport pick-up) to a confirmed or checked-in booking. It is priced for the booking's nights and guests by the extra's unit (per stay, per night, per person, per person per night), times quantity, and taxed like extras chosen at booking. It goes on the folio as its own line and the response is the updated reservation, with the new total and balance.

Body

reservation_id uuid (path)required
The reservation.
extra_id uuidrequired
quantity integer
1 to 99. Default 1.
complimentary boolean
Give it free: it goes on the bill at its price, marked complimentary with your reason, and isn't charged (the balance doesn't change). Needs the folios:write scope as well.
reason string
Why it is free, at least 3 characters, such as Honeymoon. Required with complimentary; kept on the bill.

Example

Request
curl -X POST "https://app.chatbeds.app/partner/v1/reservations/a589df05-30ad-4ee5-9832-16ff6c2c1d0e/extras" \
  -H "Authorization: Bearer cbk_••••" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: BK-104233-extra-breakfast" \
  -d '{"extra_id": "<extra id from extra.list>", "quantity": 1}'

The sandbox hotel has no extras, so there is no recorded response. The answer is 200 OK with {"reservation": {...}}, the same object as Get a reservation, its total and balance raised by the extra's amount (and tax). To see the extra's own line, read the folio.

Errors

StatusdetailWhen
409Extras cannot be added to a booking that is cancelled. (or checked out, no show)Only confirmed and checked-in bookings take extras
400... is not on offer.The hotel has switched the extra off
403The app token lacks reservations:write
404Extra not foundNot an extra of this property
404Reservation not found
422extra_id missing or not a UUID, quantity out of range

Vous créez quelque chose ?

Sur cette page