Trang này chưa được dịch, nên bạn đang đọc bản tiếng Anh.
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).
| Field | Type | Meaning |
|---|---|---|
id | uuid | Store it: every later call uses it |
ref | string | The short reference the hotel sees and the guest is told, such as A589DF |
property_id | uuid | |
status | string | confirmed, 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 |
source | string | Who 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_ref | string or null | Your reference, as you sent it |
arrival, departure | date | First night; day of departure |
nights, adults, children | integer | |
guest | object | first_name, last_name, email, phone |
room_type | object or null | {"id", "name"} |
unit | object or null | {"id", "name"} once a room is assigned; null until the hotel assigns one |
rate_plan | object or null | {"id", "name"}, or null for the room type's own rate |
currency | string | |
total | number | Everything charged on the folio (room, extras, fees, tax, charges) |
paid | number | Payments received |
balance | number | total minus paid. Negative means the hotel owes the guest a refund |
refund_due | number | What was paid beyond the total (after a cancellation or a cheaper change). The hotel owes it back. 0 otherwise. See Refunds |
payment_links | array | Card payment links that can still be paid, as payment objects. Empty when none is open |
cancellation_policy | object or null | The policy this booking is under, and what cancelling now would cost. null when the booking is not confirmed or pending. See below |
deposit | object or null | The 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 |
cancellation | object or null | When cancelled: {"fee", "reason", "cancelled_at"} |
created_at, updated_at | datetime |
The cancellation policy
cancellation_policy tells you, at any time, what the guest would pay to cancel now.
| Field | Type | Meaning |
|---|---|---|
id, name | uuid, string | The policy. null when the hotel has no policy |
free_cancellation_hours | integer or null | How many hours before arrival the guest can cancel for free |
charge_type | string | NIGHTS, PERCENTAGE, or NONE when the hotel has no policy |
charge_value | number | Nights charged, or the percent of the room price |
free_until | datetime or null | When free cancellation ends |
free_now | boolean | true if cancelling now costs nothing |
fee_now | number | The fee if cancelled now |
explanation | string | One 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.
{
"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
/properties/{property_id}/reservationsreservations:writeOperation reservation.createBooks 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
unit_id.room_type_id, it must be of that type. Without it, the hotel assigns a room later.rate_plan.id. Leave it out for the room type's own rate (rate_plan: null).YYYY-MM-DD.1.0.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. Default 0.extra_beds; each adds a place and costs extra_bed_price a night. Default 0.+14155550123.{"extra_id": uuid, "quantity": 1-99} (quantity defaults to 1). See extras.. _ : - /. Unique per partner and property: a second booking with the same value is refused.400 saying why if the code no longer applies, for example used up).rate_plan_id; the stay is linked to the company the rate is for.409 with the new total. Strongly recommended.| Header | |
|---|---|
Idempotency-Key | 1 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
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
}'{
"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
| Status | detail | What to do |
|---|---|---|
409 | The price has changed: the total is now USD 180.00. | Search offers again and show the guest the new price. Nothing was booked |
409 | A 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 |
409 | No Standard room is available for the selected dates. | Sold out since you searched. Search again |
409 | Unit is already booked for the selected dates. | The unit_id you chose is taken. Book by room type instead |
409 | The 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 |
409 | Standard is not on sale. | The room type was switched off |
409 | A request with this Idempotency-Key is already being processed. | Two requests with the same key at once. Wait and retry with the same key |
400 | Give room_type_id (and unit_id to choose the room). | Neither was sent |
400 | That unit is not of that room type. | unit_id and room_type_id disagree |
400 | external_ref: letters, digits and . _ : - / only, up to 100 characters. | Fix the reference |
400 | Standard 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 |
400 | That rate plan belongs to another property. | Wrong rate_plan_id |
400 | Idempotency-Key must be 1 to 255 characters. | |
404 | Room type not found, Unit not found, Extra not found, Property not found | An ID that is not this property's |
422 | A list of field problems | A required field is missing or out of range, or the Idempotency-Key was used for a different request |
{
"detail": [
{
"loc": [
"body",
"departure"
],
"msg": "Field required",
"type": "missing"
},
{
"loc": [
"body",
"guest"
],
"msg": "Field required",
"type": "missing"
}
]
}Get a reservation
/reservations/{reservation_id}reservations:readOperation reservation.getReturns one reservation at the property, whoever made it. Use it to refresh your copy when a webhook arrives.
Parameters
id.Example
curl -X GET "https://app.chatbeds.app/partner/v1/reservations/a589df05-30ad-4ee5-9832-16ff6c2c1d0e" \
-H "Authorization: Bearer cbk_••••"{
"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
| Status | detail | When |
|---|---|---|
403 | The app token lacks reservations:read | |
404 | Reservation not found | No such reservation at this property |
Search reservations
/properties/{property_id}/reservationsreservations:readOperation reservation.searchFinds 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
last_name also works.confirmed, checked_in, checked_out, cancelled or no_show.50.Example
curl -X GET "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/reservations?external_ref=BK-104233" \
-H "Authorization: Bearer cbk_••••"{
"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
| Status | detail | When |
|---|---|---|
400 | Search by arrival, departure, last_name or external_ref. | None of the four was given |
400 | Unknown status. Use confirmed, checked_in, checked_out, cancelled or no_show. | |
403 | The app token lacks reservations:read | |
404 | Property not found | |
422 | A date that is not a date, or limit out of range |
Modify a reservation
/reservations/{reservation_id}reservations:writeOperation reservation.modifyChanges 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
confirmed or pending). See Changing the room type or rate plan.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.children. The nights' price for more guests follows the new guests.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.How the price follows a change:
| Change | Effect on the folio |
|---|---|
| Nights kept | Keep the price they were booked at |
| New nights | Priced now, at today's rates |
| Nights dropped | Come off the folio |
| Extras sold per night | Follow the new number of nights |
| Extras sold per person | Follow the new number of guests |
| A new room type or rate plan | Every night is priced again, as a new booking would be |
| A booking with a price agreed by hand | Keeps 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
confirmedorpending. Otherwise409. - 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 (
409if not), and the guests must fit it (400if not). - The assigned room is kept if it is of the new type. Otherwise
unitbecomesnulland 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.
Payment links after a change
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
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"
}'{
"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
| Status | detail | When |
|---|---|---|
400 | Nothing to change. | The body had no field to change |
400 | Check-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 |
400 | Suite sleeps 2: 3 guests is too many. ..., Suite takes at most 2 adults. | The guests don't fit the new room type |
409 | The price has changed: the new total is USD 450.00. Preview the change again. | expected_total differs from the new total. Nothing was saved |
409 | The 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 |
409 | This booking has a price agreed with the hotel. Ask the hotel to change its room. | The hotel set the price by hand |
409 | Suite is not on sale. | The room type or rate plan was switched off |
409 | A reservation with status 'cancelled' can only have its guest details and notes changed. | Dates or guests on a cancelled or checked-out booking |
409 | The guest has already arrived, so the arrival date cannot change. | The guest is checked in |
409 | No ... 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 |
403 | The app token lacks reservations:write | |
404 | Reservation not found, Room type not found, Rate plan not found | An ID that is not this property's |
Preview a change
/reservations/{reservation_id}?dry_run=truereservations:writeOperation reservation.previewChangePrices 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
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.
{
"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
}
}| Field | Meaning |
|---|---|
before, after | The booking now, and as it would be: total, paid, balance, refund_due, currency, arrival, departure, room_type, rate_plan and each night's amount |
difference | after.total minus before.total. Negative when the change is cheaper |
dry_run | Always 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
/reservations/{reservation_id}/cancellation-quotereservations:readOperation reservation.cancellationQuoteWhat 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
Example
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:
{
"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"
}
}| Field | Meaning |
|---|---|
fee | What cancelling now charges |
free | true if cancelling now costs nothing |
free_until | When free cancellation ends, or null |
explanation | One sentence to show the guest |
policy | The cancellation policy |
refundable | true when the fee is less than the room price |
paid | What the guest has paid so far |
balance_after | What the guest would still owe after cancelling |
refund_due_after | What the hotel would owe back after cancelling |
quoted_at | When this quote was made |
Errors
| Status | detail | When |
|---|---|---|
409 | A booking that is cancelled cannot be cancelled. (or checked in, checked out, no show) | Only confirmed and pending bookings can be quoted |
403 | The app token lacks reservations:read | |
404 | Reservation not found |
Cancel a reservation
/reservations/{reservation_id}/cancelreservations:writeOperation reservation.cancelCancels 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
Example
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.
{
"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
| Status | detail | When |
|---|---|---|
409 | The guest is checked in. Check them out instead of cancelling. | |
409 | This stay is already finished and cannot be cancelled. | The guest has checked out |
403 | The app token lacks reservations:write | |
404 | Reservation not found |
Add an extra
/reservations/{reservation_id}/extrasreservations:writeOperation reservation.addExtraAdds 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
extra.list.1.reason, and isn't charged (the balance doesn't change). Needs the folios:write scope as well.Honeymoon. Required with complimentary; kept on the bill.Example
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
| Status | detail | When |
|---|---|---|
409 | Extras 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 |
403 | The app token lacks reservations:write | |
404 | Extra not found | Not an extra of this property |
404 | Reservation not found | |
422 | extra_id missing or not a UUID, quantity out of range |
Bạn đang xây dựng gì đó?