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
/properties/{property_id}/cancellation-policiespolicies:writeOperation policy.create0: never free. Default 24.PERCENTAGE of the room price, or NIGHTS. Default PERCENTAGE.false.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}'{
"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
/cancellation-policies/{policy_id}policies:writeOperation policy.updateSend 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
/cancellation-policies/{policy_id}policies:writeOperation policy.deleteRate 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
/properties/{property_id}/booking-rulesproperty:readOperation bookingRules.getEverything a guest agrees to when they book, in one place.
{
"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
}
}| Field | What it means |
|---|---|
cancellation.default_policy_id | The policy every booking follows, unless its rate plan or room type has its own |
cancellation.online_policy_id | The policy for bookings on the hotel's own booking page; null: the default |
cancellation.room_types | Each 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 |
deposit | What 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 |
children | welcome: false is adults only; min_age: children from this age. Infants under infants_under don't count against a room's size |
min_checkin_age | The youngest a guest checking in may be |
pets.allowed | NO, ON_REQUEST or YES; fee for the stay |
smoking | NO, AREAS (in some areas) or ROOMS |
early_check_in_fee, late_check_out_fee | One flat charge, when the hotel uses no time bands |
stay_times | Charges 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_out | Guests settle their bill before they check out (read only: Check out) |
Change the booking rules
/properties/{property_id}/booking-rulespolicies:writeOperation bookingRules.updateSend 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.
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}]}
}'A rate plan's own rules
/rate-plans/{rate_plan_id}/rulespolicies:writeOperation ratePlan.updateRulesA 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.
null: the hotel's.{kind, value, balance_days} as in the booking rules; null: the hotel's.{
"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.
Building something?