ChatBedsGeliştiriciler
API başvurusu

Bu sayfa henüz çevrilmedi, bu yüzden İngilizce sürümünü okuyorsunuz.

Policies and booking rules

Create and change the hotel's cancellation policies, and its booking rules: deposit, children, pets, smoking, check-in and check-out times, early and late charges, and a rate plan's own rules.

These operations change what the hotel's guests agree to when they book. They run through the same checks as the hotel's own settings screens. New bookings follow the new rules; bookings already made keep the policy, deposit and early or late charges they were made under, so a guest is never charged more than they agreed.

Reading needs property:read; every change needs policies:write. Every change takes an Idempotency-Key.

Cancellation policies

A cancellation policy says how long before arrival a guest can cancel for free, and what they pay after that: a percentage of the room price, or a number of nights. The hotel's default policy applies to every booking, unless the booking's rate plan or room category has its own. To give each room category its own, see Change the booking rules. List them with Get policies.

Create a policy

POST/properties/{property_id}/cancellation-policies
Scope policies:writeOperation policy.create
name stringrequired
Up to 255 characters, shown to guests.
description string
Up to 1,000 characters.
free_cancellation_hours integer
Free until this many hours before arrival (0 to 8,760). 0: never free. Default 24.
charge_type string
PERCENTAGE of the room price, or NIGHTS. Default PERCENTAGE.
charge_value number
The percentage (at most 100) or the number of nights (a whole number). Default 100.
is_default boolean
Make it the hotel's default. The hotel's first policy becomes the default unless this is false.
Request
curl -X POST "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/cancellation-policies" \
  -H "Authorization: Bearer cbk_••••" \
  -H "Idempotency-Key: policy-flexible-1" \
  -H "Content-Type: application/json" \
  -d '{"name": "Flexible", "free_cancellation_hours": 48, "charge_type": "NIGHTS", "charge_value": 1}'
201 Created
{
  "id": "5b0d3f3e-2c1a-4f7b-9a57-0f6e3c1d2b44",
  "property_id": "19306340-c7cf-465a-93d3-0b7873a7e85d",
  "name": "Flexible",
  "description": null,
  "free_cancellation_hours": 48,
  "charge_type": "NIGHTS",
  "charge_value": 1.0,
  "is_default": true,
  "summary": "Free until 48 hours before arrival, then 1 night."
}

Change a policy

PATCH/cancellation-policies/{policy_id}
Scope policies:writeOperation policy.update

Send only what changes, with the same fields as creating a policy. is_default: true makes it the default; false on the default leaves the hotel with no default until one is chosen. A percentage over 100 answers 400.

Delete a policy

DELETE/cancellation-policies/{policy_id}
Scope policies:writeOperation policy.delete

Rate plans, room types and bookings that used it fall back to the hotel's default. If it was the default, the hotel has none until one is chosen. Answers {"deleted": true, "id": "…"}.

Get the booking rules

GET/properties/{property_id}/booking-rules
Scope property:readOperation bookingRules.get

Everything a guest agrees to when they book, in one place.

200 OK
{
  "property_id": "19306340-c7cf-465a-93d3-0b7873a7e85d",
  "currency": "USD",
  "check_in_time": "15:00",
  "check_out_time": "11:00",
  "cancellation": {
    "default_policy_id": "5b0d3f3e-2c1a-4f7b-9a57-0f6e3c1d2b44",
    "online_policy_id": null,
    "room_types": [
      { "room_type_id": "d452e580-0ef6-4ddc-a64c-688c45731d2d", "name": "Deluxe", "policy_id": null },
      { "room_type_id": "5d7f589d-e3c2-444d-a472-153a27be5923", "name": "Suite", "policy_id": "9e7a2c55-1b3d-4e6f-8a90-c2d4e6f8a0b1" }
    ]
  },
  "deposit": {
    "kind": "PERCENT",
    "value": 30.0,
    "balance_days": 7,
    "text": "A deposit of 30% of the total at booking; the rest 7 days before arrival."
  },
  "children": { "welcome": true, "min_age": 6, "infants_under": 2 },
  "min_checkin_age": 18,
  "pets": { "allowed": "ON_REQUEST", "fee": 15.0, "notes": "Small dogs only" },
  "smoking": "NO",
  "house_rules": "Quiet after 22:00.",
  "accessibility_notes": null,
  "early_check_in_fee": 20.0,
  "late_check_out_fee": 25.0,
  "stay_times": {
    "early": [],
    "late": [
      { "from": "11:00", "to": "14:00", "charge": "AMOUNT", "value": 25.0 },
      { "from": "14:00", "to": "18:00", "charge": "PERCENT", "value": 50.0 }
    ],
    "night": null,
    "settle_before_check_out": true
  }
}
FieldWhat it means
cancellation.default_policy_idThe policy every booking follows, unless its rate plan or room type has its own
cancellation.online_policy_idThe policy for bookings on the hotel's own booking page; null: the default
cancellation.room_typesEach room category's own policy (null: the default). A booking follows its rate plan's own policy first, then its room type's, then the hotel's default
depositWhat a booking asks at booking: NONE, PERCENT of the total, an AMOUNT, or the FIRST_NIGHT. balance_days: the rest is due this many days before arrival (null: at check-in). A rate plan can have its own
childrenwelcome: false is adults only; min_age: children from this age. Infants under infants_under don't count against a room's size
min_checkin_ageThe youngest a guest checking in may be
pets.allowedNO, ON_REQUEST or YES; fee for the stay
smokingNO, AREAS (in some areas) or ROOMS
early_check_in_fee, late_check_out_feeOne flat charge, when the hotel uses no time bands
stay_timesCharges by the clock: early check-in and late check-out bands, and a night arrival band. Each band is from and to (hotel time), and its charge: FREE, PERCENT of the night, an AMOUNT, or a full NIGHT
stay_times.settle_before_check_outGuests settle their bill before they check out (read only: Check out)

Change the booking rules

PATCH/properties/{property_id}/booking-rules
Scope policies:writeOperation bookingRules.update

Send only what changes, in the shape GET answers. null clears a rule that can be empty, for example "house_rules": null. The answer is the booking rules as they are now. Rules that don't fit answer 400 with the reason (bands that overlap, a percentage deposit with no value); a value that isn't allowed answers 422.

Sending stay_times.early, late or night replaces that list or band; the others stay. Up to 6 bands each.

cancellation.room_types changes only the room categories you list: [{"room_type_id": "…", "policy_id": "…"}], with policy_id: null to put one back on the default.

Request
curl -X PATCH "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/booking-rules" \
  -H "Authorization: Bearer cbk_••••" \
  -H "Idempotency-Key: rules-2026-11-06" \
  -H "Content-Type: application/json" \
  -d '{
    "deposit": {"kind": "PERCENT", "value": 30, "balance_days": 7},
    "pets": {"allowed": "ON_REQUEST", "fee": 15, "notes": "Small dogs only"},
    "stay_times": {"late": [{"from": "11:00", "to": "14:00", "charge": "AMOUNT", "value": 25}]}
  }'
The hotel's guests see these rules on its booking page and in WhatsApp, and Ana answers from them. Changing them changes what new guests are told and charged at once.

A rate plan's own rules

PATCH/rate-plans/{rate_plan_id}/rules
Scope policies:writeOperation ratePlan.updateRules

A rate plan can have its own cancellation policy and deposit, in place of the hotel's, and its own length of stay. A non-refundable rate is the usual example.

cancellation_policy_id uuid
Its own policy; null: the hotel's.
refundable boolean
Whether the rate can be refunded.
min_stay_nights integer
1 to 365.
max_stay_nights integer
1 to 365, at least the minimum.
deposit object
{kind, value, balance_days} as in the booking rules; null: the hotel's.
200 OK
{
  "id": "0c4b6a51-8d0e-4bb8-a3f3-7a1c9b2e4d10",
  "name": "Non-refundable",
  "is_refundable": false,
  "min_stay_nights": 2,
  "max_stay_nights": null,
  "cancellation_policy_id": "9e7a2c55-1b3d-4e6f-8a90-c2d4e6f8a0b1",
  "deposit_kind": "FIRST_NIGHT",
  "deposit_value": null,
  "balance_days": null
}

List rate plans shows each plan's deposit (null: the hotel's) and cancellation_policy_id.

Bir şey mi geliştiriyorsunuz?

Bu sayfada