Halaman ini belum diterjemahkan, jadi Anda membaca versi bahasa Inggris.
Rooms and rates
Read a property's room types, rate plans, rooms, extras and policies, the catalog you show guests before they book.
These reads describe what the hotel sells and on what terms. They change rarely: cache them and refresh every few hours, or when an offer mentions an ID you do not know. Prices for actual dates come from offer search, not from here.
All five take the property in the path. A property_id other than the credential's own answers 404 Property not found.
List room types
/properties/{property_id}/room-typesrooms:readOperation roomType.listReturns every room type of the property, active or not, in the hotel's own order, with its description, occupancy, base price, amenities, photos, videos and how many active rooms it has.
Parameters
GET /me.updated_at you have seen and send it next time to sync only what changed.Example
curl -X GET "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/room-types" \
-H "Authorization: Bearer cbk_••••"{
"room_types": [
{
"id": "da3b4c87-c1ca-4f13-8c90-066900f16d48",
"name": "Standard",
"description": null,
"base_price": 90.0,
"currency": "USD",
"max_occupancy": 2,
"max_adults": null,
"max_children": null,
"bed_type": null,
"size_sqm": null,
"amenities": [],
"photos": [],
"units": 6,
"active": true
},
{
"id": "cd4932a5-a172-4147-bfd6-fcd79a42af11",
"name": "Deluxe",
"description": null,
"base_price": 140.0,
"currency": "USD",
"max_occupancy": 3,
"max_adults": null,
"max_children": null,
"bed_type": null,
"size_sqm": null,
"amenities": [],
"photos": [],
"units": 4,
"active": true
}
// ... one more (Suite)
]
}| Field | Meaning |
|---|---|
base_price | The room type's standard nightly price. The price for real dates can differ: use offers |
max_occupancy, max_adults, max_children | Guests it takes in total, and limits by age group (null means no separate limit) |
description | The hotel's description of the room, plain text (line breaks kept); null when none |
photos, videos | Image and video URLs, main photo first. Kept for compatibility: media says more |
media | Photos then videos, in the hotel's order: see room type media |
features | Codes: pets_allowed; wheelchair_accessible, step_free, roll_in_shower, grab_rails, hearing_accessible, visual_aids, lowered_bed; non_smoking or smoking; private_bathroom, shared_bathroom, bathtub, shower; view_sea, view_city, view_garden, view_mountain, view_pool; balcony, terrace, kitchenette, kitchen, workspace, connecting, family_room. New codes may be added: ignore those you don't know |
beds | [{"type": "king", "count": 1}]; types king, queen, double, single, sofa_bed, bunk, futon |
cots, extra_beds, extra_bed_price | How many can be added, and an extra bed's price a night (null: free) |
pricing | More guests: the price covers base_occupancy guests (null: everyone it sleeps); each guest over it pays extra_adult_price a night, a child the price of their band in child_bands ({"from", "to", "price"}, ages inclusive) or the adult price; children under infants_under are free |
units | Active rooms of this type |
active | false when the hotel has stopped selling it. Inactive types never appear in offers |
updated_at | When the room type last changed (ISO 8601, UTC) |
cancellation_policy_id | The room type's own cancellation policy, used unless the booking's rate plan has one; null: the hotel's default. See policies |
Caching
Every room type read answers with an ETag and Cache-Control: private, max-age=60. Send the ETag back in
If-None-Match: when nothing changed the answer is 304 Not Modified with no body. Together with updated_since, a
connector can check every few minutes for almost nothing.
Errors
| Status | When |
|---|---|
403 | The app token lacks rooms:read |
404 | Property not found: not the credential's property |
Get one room type
/properties/{property_id}/room-types/{room_type_id}rooms:readOperation roomType.getThe same fields as one item of the list, as {"room_type": {...}}. Use it to refresh a single room's description,
photos and videos.
curl "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/room-types/cd4932a5-a172-4147-bfd6-fcd79a42af11" \
-H "Authorization: Bearer cbk_••••" -H 'If-None-Match: "3f1c…"'Errors
| Status | When |
|---|---|
304 | Unchanged since the ETag sent in If-None-Match |
403 | The app token lacks rooms:read |
404 | Room type not found, or not the credential's property |
Get a room type's photos and videos
/properties/{property_id}/room-types/{room_type_id}/mediarooms:readOperation roomType.mediaThe room type's photos then videos, each with what you need to show it well.
{
"room_type_id": "cd4932a5-a172-4147-bfd6-fcd79a42af11",
"updated_at": "2026-10-17T13:24:07+00:00",
"media": [
{ "id": "5b8e0c1d-2f7a-4c55-9a51-0f4c1d2e3b6a", "kind": "photo", "position": 0, "alt": "King bed facing the garden",
"url": "https://app.chatbeds.app/public/v1/media/5b8e0c1d-2f7a-4c55-9a51-0f4c1d2e3b6a",
"hosted": true, "mime_type": "image/jpeg", "size": 284113 },
{ "id": null, "kind": "photo", "position": 1, "alt": "Pool", "url": "https://hotel.example/pool.jpg",
"hosted": false, "mime_type": null, "size": null },
{ "id": "8d2b6f4e-1c3a-4e7b-b0d9-6a5f2c1e9d07", "kind": "video", "position": 0, "alt": null,
"url": "https://app.chatbeds.app/public/v1/media/8d2b6f4e-1c3a-4e7b-b0d9-6a5f2c1e9d07",
"hosted": true, "mime_type": "video/mp4", "size": 18234880 }
]
}| Field | Meaning |
|---|---|
kind | photo or video |
position | Order within its kind; photo 0 is the main photo |
alt | The hotel's description of a photo, for screen readers; null when none (and for videos) |
hosted | true: the file is kept by ChatBeds. Its URL never changes and needs no credential, so cache or copy it for good; videos answer byte-range requests (Range), for streaming. false: a link the hotel pasted (its own site, YouTube): fetch it from there, it may change |
id, mime_type, size | For hosted files only: the file's id, type (image/jpeg, image/png, image/webp, video/mp4, video/webm, video/quicktime) and size in bytes |
Good practice: download hosted photos once and serve them from your own CDN, keyed by id; a photo the hotel
removes disappears from media (and its URL then answers 404), so drop it on your side when it is gone.
Errors
| Status | When |
|---|---|
304 | Unchanged since the ETag sent in If-None-Match |
403 | The app token lacks rooms:read |
404 | Room type not found, or not the credential's property |
List rate plans
/properties/{property_id}/rate-plansrooms:readOperation ratePlan.listReturns the hotel's rate plans: named ways of selling a room (with breakfast, non-refundable, long stay), each with its stay rules and cancellation policy. A plan with room_type_id set applies only to that room type; null means any. The sandbox has none, so the list is empty until you add one in the sandbox hotel.
Parameters
Example
curl -X GET "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/rate-plans" \
-H "Authorization: Bearer cbk_••••"{
"rate_plans": []
}Each item has these fields:
| Field | Type | Meaning |
|---|---|---|
id | uuid | Pass it as rate_plan_id when booking |
name, description | string | As the hotel wrote them |
room_type_id | uuid or null | The one room type it applies to, or null for any |
meal_plan | string or null | Meals included, as the hotel set it |
refundable | boolean | false for a non-refundable plan |
default | boolean | The hotel's default plan |
active | boolean | Whether it is on sale |
min_stay_nights | integer | Shortest stay (at least 1) |
max_stay_nights | integer or null | Longest stay, if any |
cancellation_policy_id | uuid or null | Its own cancellation policy; null means the hotel's default applies. See policies |
Errors
| Status | When |
|---|---|
403 | The app token lacks rooms:read |
404 | Property not found |
List units
/properties/{property_id}/unitsrooms:readOperation unit.listReturns the physical rooms ("units"), sorted by name, with their room type and housekeeping status. You need them only to book a specific room (unit_id) or to show room numbers.
Parameters
Example
curl -X GET "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/units" \
-H "Authorization: Bearer cbk_••••"{
"units": [
{
"id": "00635381-d0c0-4383-9bc0-7c74bfac07ec",
"name": "101",
"room_type_id": "da3b4c87-c1ca-4f13-8c90-066900f16d48",
"floor": null,
"status": "OCCUPIED",
"active": true
},
{
"id": "b1104463-171d-4f9e-8a65-a915207b1cba",
"name": "103",
"room_type_id": "da3b4c87-c1ca-4f13-8c90-066900f16d48",
"floor": null,
"status": "CLEAN",
"active": true
}
// ... 10 more
]
}status is the housekeeping state today: CLEAN, DIRTY, CLEANING, INSPECTING, READY, OCCUPIED, MAINTENANCE or DND. It says nothing about whether the room is free on future dates; use offers for that.
Errors
| Status | When |
|---|---|
403 | The app token lacks rooms:read |
404 | Property not found |
List extras
/properties/{property_id}/extrasrooms:readOperation extra.listReturns the extras on sale (breakfast, airport pick-up, late check-out) with their price and how they are charged. Add them when booking (extras) or later with reservation.addExtra, free if you like (complimentary). Manage the catalogue itself with extra.create, extra.update and extra.delete. Only active extras are listed. The sandbox has none, so the list is empty until you add one in the sandbox hotel.
Parameters
Example
curl -X GET "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/extras" \
-H "Authorization: Bearer cbk_••••"{
"extras": []
}Each item has these fields:
| Field | Type | Meaning |
|---|---|---|
id | uuid | Pass it as extra_id |
name, description | string | As the hotel wrote them |
price | number | The price of one |
unit | string | How it is charged: per_stay, per_night, per_person or per_person_per_night |
currency | string | The property's currency |
room_type_ids | uuid[] | Sold only with these room types; empty: every room type. Adding one to a booking of another room type is refused (400) |
included | boolean | Complimentary: comes free with the room. Show it as included; it cannot be added or charged (400) |
The amount charged is price times the quantity, times the nights for a per-night extra, times the guests (adults plus children) for a per-person extra.
Errors
| Status | When |
|---|---|
403 | The app token lacks rooms:read |
404 | Property not found |
Add an extra to the catalogue
/properties/{property_id}/extrasextras:writeOperation extra.createAdds an extra to the hotel's catalogue: it is offered on the booking page, the guest's page, the front desk and this API at once.
Airport pick-up.food, transport, room, experience or other.per_stay (default), per_night, per_person or per_person_per_night.0), shown as included and never charged.true.curl -X POST "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/extras" \
-H "Authorization: Bearer cbk_••••" -H "Content-Type: application/json" \
-d '{"name": "Airport pick-up", "price": 30, "unit": "per_stay", "category": "transport"}'{
"extra": {
"id": "0f6a2c91-3e7b-4d58-a1c4-9b2e7f5d3a60",
"property_id": "19306340-c7cf-465a-93d3-0b7873a7e85d",
"name": "Airport pick-up",
"description": null,
"category": "transport",
"price": 30.0,
"unit": "per_stay",
"unit_label": "per stay",
"is_active": true,
"sort_order": 1,
"currency": "USD",
"times_sold": 0,
"room_type_ids": [],
"included": false
}
}Change an extra
/extras/{extra_id}extras:writeOperation extra.updateSend only the fields to change; same fields as above. Bills already made keep the price they were charged at. Setting included to true makes its price 0.
curl -X PATCH "https://app.chatbeds.app/partner/v1/extras/0f6a2c91-3e7b-4d58-a1c4-9b2e7f5d3a60" \
-H "Authorization: Bearer cbk_••••" -H "Content-Type: application/json" \
-d '{"price": 35, "is_active": true}'Remove an extra
/extras/{extra_id}extras:writeOperation extra.deleteAn extra nobody has bought yet is deleted: {"deleted": true}. One already on a guest's bill is taken off sale instead, so the bill still shows it: {"deleted": false, "extra": {...}} with is_active: false.
Errors
| Status | When |
|---|---|
400 | A field is wrong (an unknown unit or category, a room type of another property) |
403 | The app token lacks extras:write |
404 | Not an extra of this property |
Get policies
/properties/{property_id}/policiesproperty:readOperation policy.getReturns the hotel's terms: check-in and check-out times, tax, fees charged on every stay, and its cancellation policies. Show the cancellation terms to the guest before they book: when you cancel, the hotel's policy applies and you cannot waive its fee. To change the policies and the other booking rules, see Policies and booking rules.
Parameters
Example
curl -X GET "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/policies" \
-H "Authorization: Bearer cbk_••••"{
"check_in_time": "14:00",
"check_out_time": "12:00",
"currency": "USD",
"tax": {
"rate": 16.0,
"included_in_prices": false,
"taxes": [
{"name": "Sales tax", "kind": "percent", "value": 16.0, "applies_to": "both", "included_in_prices": false,
"children_under": null, "max_nights": null, "description": "Sales tax 16%"},
{"name": "City tax", "kind": "per_person_night", "value": 200.0, "applies_to": "room", "included_in_prices": false,
"children_under": 12, "max_nights": 7, "description": "City tax PKR 200 a guest a night (children under 12 free), first 7 nights only"}
]
},
"fees": [],
"cancellation_policies": [],
"default_cancellation_policy_id": null
}| Field | Meaning |
|---|---|
tax.rate | A percentage, for example 8.875 |
tax.included_in_prices | true: prices already contain the tax. false: tax is added on top |
tax.taxes[] | Each of the hotel's taxes. kind: percent (of the room, extras or both), per_person_night or per_room_night. children_under: children don't pay a per-guest tax. max_nights: only the first nights. tax.rate is the percents added together, kept for older code |
fees[] | {"name", "amount", "per": "stay"}. Charged once on every stay (today: the cleaning fee) |
cancellation_policies[] | id, name, description (a sentence such as "Free until 48 hours before arrival, then 1 night."), default, free_cancellation_hours, charge_type (PERCENTAGE of the room price, or NIGHTS), charge_value |
default_cancellation_policy_id | The policy that applies when neither the rate plan nor the room type has its own. null and no policy means cancelling is free |
Which policy applies to a booking: the rate plan's own policy if it has one, otherwise the room type's own
(cancellation_policy_id on the room type), otherwise the hotel's default. A non-refundable plan with no policy of its own charges the room price whenever it is cancelled.
Errors
| Status | When |
|---|---|
403 | The app token lacks property:read |
404 | Property not found |
Sedang membangun sesuatu?