ChatBeds开发者
API 参考

本页尚未翻译,你正在阅读英文版。

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

GET/properties/{property_id}/room-types
Scope rooms:readOperation roomType.list

Returns 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

property_id uuid (path)required
The property, from GET /me.
updated_since ISO 8601 (query)
Only room types changed at or after this time (inclusive, so nothing changed in that same instant is missed). Keep the newest updated_at you have seen and send it next time to sync only what changed.

Example

Request
curl -X GET "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/room-types" \
  -H "Authorization: Bearer cbk_••••"
200 OK
{
  "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)
  ]
}
FieldMeaning
base_priceThe room type's standard nightly price. The price for real dates can differ: use offers
max_occupancy, max_adults, max_childrenGuests it takes in total, and limits by age group (null means no separate limit)
descriptionThe hotel's description of the room, plain text (line breaks kept); null when none
photos, videosImage and video URLs, main photo first. Kept for compatibility: media says more
mediaPhotos then videos, in the hotel's order: see room type media
featuresCodes: 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_priceHow many can be added, and an extra bed's price a night (null: free)
pricingMore 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
unitsActive rooms of this type
activefalse when the hotel has stopped selling it. Inactive types never appear in offers
updated_atWhen the room type last changed (ISO 8601, UTC)
cancellation_policy_idThe 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

StatusWhen
403The app token lacks rooms:read
404Property not found: not the credential's property

Get one room type

GET/properties/{property_id}/room-types/{room_type_id}
Scope rooms:readOperation roomType.get

The same fields as one item of the list, as {"room_type": {...}}. Use it to refresh a single room's description, photos and videos.

Request
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

StatusWhen
304Unchanged since the ETag sent in If-None-Match
403The app token lacks rooms:read
404Room type not found, or not the credential's property

Get a room type's photos and videos

GET/properties/{property_id}/room-types/{room_type_id}/media
Scope rooms:readOperation roomType.media

The room type's photos then videos, each with what you need to show it well.

200 OK
{
  "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 }
  ]
}
FieldMeaning
kindphoto or video
positionOrder within its kind; photo 0 is the main photo
altThe hotel's description of a photo, for screen readers; null when none (and for videos)
hostedtrue: 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, sizeFor 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

StatusWhen
304Unchanged since the ETag sent in If-None-Match
403The app token lacks rooms:read
404Room type not found, or not the credential's property

List rate plans

GET/properties/{property_id}/rate-plans
Scope rooms:readOperation ratePlan.list

Returns 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

property_id uuid (path)required
The property.

Example

Request
curl -X GET "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/rate-plans" \
  -H "Authorization: Bearer cbk_••••"
200 OK
{
  "rate_plans": []
}

Each item has these fields:

FieldTypeMeaning
iduuidPass it as rate_plan_id when booking
name, descriptionstringAs the hotel wrote them
room_type_iduuid or nullThe one room type it applies to, or null for any
meal_planstring or nullMeals included, as the hotel set it
refundablebooleanfalse for a non-refundable plan
defaultbooleanThe hotel's default plan
activebooleanWhether it is on sale
min_stay_nightsintegerShortest stay (at least 1)
max_stay_nightsinteger or nullLongest stay, if any
cancellation_policy_iduuid or nullIts own cancellation policy; null means the hotel's default applies. See policies

Errors

StatusWhen
403The app token lacks rooms:read
404Property not found

List units

GET/properties/{property_id}/units
Scope rooms:readOperation unit.list

Returns 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

property_id uuid (path)required
The property.

Example

Request
curl -X GET "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/units" \
  -H "Authorization: Bearer cbk_••••"
200 OK
{
  "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

StatusWhen
403The app token lacks rooms:read
404Property not found

List extras

GET/properties/{property_id}/extras
Scope rooms:readOperation extra.list

Returns 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

property_id uuid (path)required
The property.

Example

Request
curl -X GET "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/extras" \
  -H "Authorization: Bearer cbk_••••"
200 OK
{
  "extras": []
}

Each item has these fields:

FieldTypeMeaning
iduuidPass it as extra_id
name, descriptionstringAs the hotel wrote them
pricenumberThe price of one
unitstringHow it is charged: per_stay, per_night, per_person or per_person_per_night
currencystringThe property's currency
room_type_idsuuid[]Sold only with these room types; empty: every room type. Adding one to a booking of another room type is refused (400)
includedbooleanComplimentary: 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

StatusWhen
403The app token lacks rooms:read
404Property not found

Add an extra to the catalogue

POST/properties/{property_id}/extras
Scope extras:writeOperation extra.create

Adds 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.

name stringrequired
Up to 120 characters, such as Airport pick-up.
description string
Up to 1,000 characters.
category string
food, transport, room, experience or other.
price number
The price of one. Not needed for an included extra.
unit string
per_stay (default), per_night, per_person or per_person_per_night.
room_type_ids array of uuid
Sold only with these room types. Leave out for every room type.
included boolean
Complimentary: comes free with the room (its price is 0), shown as included and never charged.
is_active boolean
On sale. Default true.
Request
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"}'
201 Created
{
  "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

PATCH/extras/{extra_id}
Scope extras:writeOperation extra.update

Send 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.

Request
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

DELETE/extras/{extra_id}
Scope extras:writeOperation extra.delete

An 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

StatusWhen
400A field is wrong (an unknown unit or category, a room type of another property)
403The app token lacks extras:write
404Not an extra of this property

Get policies

GET/properties/{property_id}/policies
Scope property:readOperation policy.get

Returns 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

property_id uuid (path)required
The property.

Example

Request
curl -X GET "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/policies" \
  -H "Authorization: Bearer cbk_••••"
200 OK
{
  "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
}
FieldMeaning
tax.rateA percentage, for example 8.875
tax.included_in_pricestrue: 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_idThe 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

StatusWhen
403The app token lacks property:read
404Property not found

正在开发什么?

本页内容