Managing property settings
Use the Property API settings
endpoint to add, update or retrieve property settings.
For example, using this endpoint, you can specify whether the property:
- Accepts child guests and define their age range
- Accepts pets and their policy
- Requires booker address and phone number when guests book
You can also specify:
- The house rules for the property
- Country-specific invoice, tax and finance details that Booking.com requires before you can set a property open and bookable.
To specify cancellation and prepayment policies, see the Policies API. To specify property settings for a property, you must have already created a property. For more information, see creating a property using the Property API.
This topic helps you:
Creating or updating property settings
POST
https://supply-xml.booking.com/property-api/properties/{{property_id}}/settings
Use the property-api
settings endpoint to create or update property settings by specifying details such as curfew, age restrictions, pets policy, cancellation exceptions, quiet hours, renovation dates when the property might likely not be available for bookings, and so on.
All the settings are optional
The request body accepts property settings in groups. All the settings are optional. However, when you specify settings for a group, some settings in the group can be mandatory. For example, you can send a request to set:
- Damage policy
- Quiet hours or Curfew timing
- long stay details
- pets policy
- children policy and so on.
In each request, you can specify a single setting or multiple settings for a property. The endpoint validates and returns the response status as a group of settings. Each group of settings is processed individually.
Header parameter
The following table describes the elements you can add in the header:
Header | Description | Type | Required/ Optional | Notes |
---|---|---|---|---|
Content-Type: application/json | Specifies the expected content type. | string | Required |
Path parameter
The following table describes the elements you can add in the path:
Value | Description | Type | Required/ Optional | Notes |
---|---|---|---|---|
{property ID } value | Specify the unique ID of the property to update its details. | integer | Required |
Request body
The following is a request body example:
Click to view the request body example.
{ "property_settings": { "require_cvc": true, "view_cc_details": true, "curfew": { "enabled": true, "start": "18:00", "end": "09:00" }, "require_booker_address": true, "require_booker_phone_number": true, "age_restriction": { "enabled": true, "min": 18, "max": 99 }, "auto_replenish": true, "replenish_closed_rooms": true, "long_stay": { "enabled": true, "max_length_of_stay": 45 }, "pricing_type": "Standard", "allow_smoking": true }, "pets": { "pets_allowed": "PETS_NOT_ALLOWED", "pets_price_type": "FREE" }, "damage_policy": { "amount": 90, "policy_type": "HANDLED_BY_PROPERTY", "damage_programme_terms_agreed": false, "collection_mode": "CASH", "return_mode": "CASH", "collection_when": "ON_ARRIVAL", "return_when": "ON_CHECKOUT" }, "standard_phrases": [ { "name": "GuestIdentification", "enabled": true } ], "quiet_hours": { "enabled": true, "start": "18:00", "end": "08:30" }, "renovation": { "enabled": true, "start": "2014-01-01", "end": "2014-01-10" }, "bed_linen_policy": { "enabled": true, "amount": 100.0 }, "accepted_payment_types": { "codes": [ 1, 2, 55 ] }, "french_tax_details": { "category_id": "11", "nature_id": "1", "declare_revenue": true, "has_vat": true, "registered_in_rcs": true }, "cancellation_exceptions" : { "grace_period": { "enabled": true, "after_booking": "HOURS_4" }, "advance_cancellation": { "enabled": true, "before_check_in": "WEEKS_4" } }, "age_buckets": [ { "min_age": 1, "max_age": 10 } ], "children_policies": { "allow_children": true, "min_age": 0, "policy_rules": [ { "rule_type": "EXISTING_BED", "from_age": 0, "to_age": 10, "price_type": "FIXED", "price_mode": "PER_STAY", "price": 0 } ] }, "booking_model": { "type": "IB" }, "invoice_settings": { "legal_name": "string", "contact_person": "string", "address": "string", "country_code": "string", "city": "string", "postal_code": "string", "state": "st", "notification_channel": "POSTAL_MAIL", "brazil_tax_details": { "tax_payer_number_type": "CNPJ", "tax_payer_number": "string", "city_hall_id": "string", "email": "string" } } }
Request body elements
The following table describes the request body elements.
Object | Attribute | Description | Type | Optional/Required | Notes | Root parameter in HDCN |
---|---|---|---|---|---|---|
> property_settings | Contains multiple various settings related to the property. | object | Optional | |||
require_cvc | Specifies whether the guest needs to provide CVC details for the booking. | boolean | Optional | Default: false | HotelInfo > TPA_Extensions > PaymentPreferences | |
view_cc_details | Specifies whether a trusted property can view the guest's credit card details on Extranet. | boolean | Optional | Default: false | HotelInfo > TPA_Extensions > PaymentPreferences | |
require_booker_address | Specifies whether the guests must provide a contact address. | boolean | Optional | Default: false | TPA_Extensions > GuestInformation > RequireGuestAddress | |
require_booker_phone_number | Specifies whether the guests must provide a contact telephone number. | boolean | Optional | Default: false | TPA_Extensions > GuestInformation > RequireGuestContactNumber | |
auto_replenish | Specifies if property is enabled to auto-replenish and is used to make a room available to sell again after a cancellation. | boolean | Optional | Default: true | ||
replenish_closed_rooms | Reopen closed rooms after a cancellation. This will open a closed room after a cancellation is received. | boolean | Optional | Default: true. This option will only work if auto_replenish=true . | ||
pricing_type | Specifies the property's pricing type. Can be Standard , LOS or OBP . For more information, see pricing types. | enum | Optional | Default: Standard | TPA_Extensions > PricingType | |
allow_smoking | Specifies whether the property allows smoking. | boolean | Optional | Default: true | House-Rules API | |
>> curfew | Contains curfew settings for the property. | object | Optional | Curfew start and end cannot be overlaped with property check-in and check-out times. | ||
enabled | Specifies whether the property has curfew time enabled. | boolean | Required | TPA_Extensions > GuestInformation > HasCurfew | ||
start | Time when curfew starts. Accepts the format: HH:MM . Only effective when enabled=true . | boolean | Optional | Required if enabled=true . | TPA_Extensions > GuestInformation > CurfewStart | |
end | Time when curfew ends. Accepts the format: HH:MM . Only effective when enabled=true . | boolean | Optional | Required if enabled=true . | TPA_Extensions > GuestInformation > CurfewEnd | |
>> age_restriction | Contains whether there is an age limit to check-in. | object | Optional | |||
enabled | Specify whether age restriction is enabled | boolean | Required | TPA_Extensions > GuestInformation > HasAgeRestriction | ||
min | Specifies the minimum allowed age for guests to check-in. Allowed age range: 18-99. Only effective when enabled=true . | boolean | Optional | Required if enabled=true . | TPA_Extensions > GuestInformation > AgeRestrictionMin | |
max | Specifies the maximum allowed age for guests to check-in. Allowed age range: 18-99. Only effective when enabled=true . | boolean | Optional | Required if enabled=true . | TPA_Extensions > GuestInformation > AgeRestrictionMax | |
>> long_stay | Contains whether property accepts a stay longer than 30 nights. | object | Optional | |||
enabled | Specifies whether the property has a long stay option enabled. | boolean | Required | TPA_Extensions > LongStayInfo > AcceptLongStay | ||
max_length_of_stay | Specifies the maximum number of days allowed to stay at the property. Can be one of the values: 45, 60, 75, 90. | integer | Optional | Default: 90 if long stay option is enabled. | TPA_Extensions > LongStayInfo > MaxLengthOfStay | |
> pets | Contains settings related to pets policy. | object | Optional | House-Rules API | ||
allow_pets | Specifies whether pets are allowed at the property. Possible values are: - PETS_ALLOWED , - PETS_NOT_ALLOWED and - PETS_ALLOWED_ON_REQUEST . | enum | Required | |||
pets_price_type | Specifies pets price type option for the property. Possible values are: - FREE - CHARGES_MAY_APPLY . | enum | Optional | |||
> damage_policy | Contains settings related to damage policy. | object | Optional | TPA_Extensions > StandardPhrases | ||
amount | Specifies the amount on which the damage deposit or programme is applicable for | double | Required | Default: 0.0 | ||
currency | Specifies the currency in which the claim and limit occurs. | string | Optional | Default is Property Currency if not specified. | ||
policy_type | Specifies the policy that is applicable. Possible values are: - NONE , - HANDLED_BY_PROPERTY and - HANDLED_BY_BOOKING_COM . | enum | Required | Default: NONE. HANDLED_BY_PROPERTY - Guests pay you a damage deposit directly. HANDLED_BY_BOOKING_COM - Guests only pay if they cause damage during their stay, facilitated by Booking.com | ||
damage_programme_terms_agreed | Specifies if you agree to the terms for the damage programme. To view damage deposit terms, you can make GET call to /legal/damage-programme/terms endpoint | boolean | Optional | Default: false. Required if you are applying for HANDLED_BY_BOOKING_COM . You can only enrol if you agree to the terms which are provided to you. | ||
collection_mode | Specifies how you would collect damage deposit. Possible values are: - CASH , - CREDIT_CARD , - PAYPAL , - BANK_TRANSFER and - OTHER . | enum | Optional | Only applicable for HANDLED_BY_PROPERTY . | ||
collection_when | Specifies when you would collect the damage deposit. Possible values are: - ON_ARRIVAL , - SEVEN_DAYS_BEFORE_ARRIVAL and - FOURTEEN_DAYS_BEFORE_ARRIVAL . | enum | Optional | Only applicable for HANDLED_BY_PROPERTY . If collection_mode is CASH then only ON_ARRIVAL is allowed for collection_when . | ||
return_mode | Specifies how you would return the damage deposit. Possible values are: - CASH , - CREDIT_CARD , - PAYPAL , - BANK_TRANSFER and - OTHER . | enum | Optional | Only applicable for HANDLED_BY_PROPERTY . | ||
return_when | Specifies when you would return the damage deposit. Possible values are: - ON_CHECKOUT , - WITHIN_7_DAYS and - WITHIN_14_DAYS . | enum | Optional | Only applicable for HANDLED_BY_PROPERTY . If return_mode is CASH then only ON_CHECKOUT is allowed for return_when . | ||
> standard_phrases | Contains settings related to standard phrases. You can send 1 or multiple standard phrases that you want to enable or remove. | array of objects | Optional | TPA_Extensions > StandardPhrases | ||
name | Specifies the name of the standard phrase. For a full list of Booking.com supported standard phrases, see StandardPhrase. | enum | Required | |||
enabled | Specifies if standard phrase should be enabled or removed. | boolean | Required | |||
> quiet_hours | Contains settings related to quiet hours of the property. | object | Optional | House-Rules API | ||
enabled | Specifies whether the property has quiet hours enabled. | boolean | Required | |||
start | Specifies the quiet hours start time. Accepts the format" HH:mm | string | Optional | Required if enabled=true . | ||
end | Specifies the quiet hours end time. Accepts the format: HH:mm | string | Optional | Required if enabled=true . | ||
> renovation | Contains settings related to renovation dates. | object | Optional | TPA_Extensions > StandardPhrases | ||
enabled | Specifies whether renovation dates are enabled. | boolean | Required | |||
start | Specifies the renovation start date. Accepts the format: yyyy-mm-dd . | string | Optional | Required if enabled=true . | ||
end | Specifies the renovation end date. Accepts the format: yyyy-mm-dd . | string | Optional | Required if enabled=true . | ||
> bed_linen_policy | Contains renting details for bed linens and towels as they are not included in the room rate. Guests can rent them at the property for an additional charge or bring their own. | object | Optional | TPA_Extensions > StandardPhrases | ||
enabled | Specifies whether the option to rent bed linen is enabled. | boolean | Required | |||
amount | Specifies the cost of renting bed linens and towels specified in the property's default currency. | double | Optional | Required if enabled=true . | ||
> accepted_payment_types | Contains settings related to payment methods. | object | Optional | |||
codes | Specifies the list of supported payment methods. For a full list of payment codes, see Booking.com Payment Type Codes. | array of integers | Required | TPA_Extensions > AcceptedPayments | ||
> french_tax_details | Contains settings related to tax details. Only applicable for countries: France, Martinique, Guadeloupe, French Guiana, Reunion, Mayotte. | object | Optional | Required to setup for properties located in the specified countries in order to go Open/Bookable. | TPA_Extensions > PropertyTaxInfo | |
category_id | Contains a number - city tax category ID. You can retrieve available categories using the /xml/citytaxcategory call. | string | Optional | TPA_Extensions > PropertyTaxInfo > PropertyTaxCategory | ||
nature_id | Contains a number - nature category ID. You can retrieve available categories using /xml/citytaxcategory call. | string | Optional | TPA_Extensions > PropertyTaxInfo > PropertyNatureCategory | ||
declare_revenue | Specifies whether the property declares revenues as professional for direct tax purposes. | boolean | Required | TPA_Extensions > PropertyTaxInfo > PropertyDeclaresRevenue | ||
has_vat | Specifies whether the property has a registered VAT for this activity. | boolean | Required | TPA_Extensions > PropertyTaxInfo > PropertyHasVat | ||
registered_in_rcs | Specifies whether the property is registered as a professional at the trade commercial register (Registre du Commerce et des Sociétés). | boolean | Required | TPA_Extensions > PropertyTaxInfo > PropertyRegisteredInVcs | ||
> cancellation_exceptions | Contains settings related to cancellation for non-refundable policy. | object | Optional | TPA_Extensions > CancellationGracePeriod | ||
>>grace_period | Optional | |||||
enabled | Specifies whether the property has a grace period enabled. | boolean | Optional | |||
after_booking | Amount of hours after booking when free cancellation is available. Can be one of the values: HOUR_1 , HOURS_4 or HOURS_24 . | enum | Required | TPA_Extensions > CancellationGracePeriod > HoursAfterBooking | ||
>>advance_cancellation | Optional | |||||
enabled | Specifies whether the property has a advance cancellation enabled. | Optional | ||||
before_check_in | Advance cancellation - amount of weeks before check-in when free cancellation is available. Can be one of the values: WEEKS_4 , WEEKS_8 or WEEKS_12 . | enum | Required | TPA_Extensions > CancellationGracePeriod > WeeksBeforeCheckIn | ||
> age_buckets | Contains age bucket details. When setting flexible children pricing, you can use the age bucket you set here to specify the age range to which the pricing applies. | array of objects | Optional | No age bucket set up by default. You can create up to three age buckets per property. Each age bucket contains a minimum and maximum age, where the maximum age is inclusive. Age buckets can't overlap with each other. | TPA_Extensions > AgeBuckets | |
min_age | Specifies the minimum age for the age bucket. | integer | Required | Policies > TPA_Extensions > AgeBuckets > AgeBucket > MinAge | ||
max_age | Specifies the maximum age for the age bucket. | integer | Required | Policies > TPA_Extensions > AgeBuckets > AgeBucket > MaxAge | ||
> children_policies | You can indicate whether a property accepts children and specify the following: the minimum age children are welcome and additional rules for existing/extra bed or crib. | object | Optional | |||
allow_children | Specifies whether the property admits adults and children, or only adults. | boolean | Optional | Policies > Policy > PolicyInfo > AcceptedGuestType | ||
min_age | Specifies the minimum age of children allowed to stay at the property. | integer | Optional | Applies only when allow_children = true . | Policies > Policy > PolicyInfo > MinGuestAge | |
>> policy_rules | You can specify a different price and rules for children staying in EXISTING_BED and specify a price for children staying in CRIB or EXTRA_BED . | array of objects | Optional | Applies only when allow_children = true . Rules ages cannot be overlapped with other rules that have the same type. | Policies > Policy > FeePolicies | |
rule_type | Specifies the rule type for which this rule applies. Possible values are: - EXISTING_BED - EXTRA_BED - CRIB ). | enum | Required | Policies > Policy > FeePolicies > Code | ||
from_age | Specifies the minimum age for the children policy to apply. In combination with to_age it becomes an age range. | integer | Required | Policies > Policy > FeePolicies > MinAge | ||
to_age | Specifies the maximum age for the children policy to apply. | integer | Required | Policies > Policy > FeePolicies > MaxAge | ||
price_type | Specifies if the rule is FREE or has FIXED price. Set FREE if price is null or FIXED when specifying a price. | enum | Required | |||
price_mode | Specifies the unit of time on which the charge is calculated. Can be PER_NIGHT or PER_STAY . | enum | Required | Policies > Policy > FeePolicies > ChargeFrequency | ||
price | Specifies the amount charged in the country's local currency. | double | Optional | Required if price_type=FIXED . | Policies > Policy > FeePolicies > Amount | |
> booking_model | You can indicate that property can have request to book option | object | Optional | |||
type | Specifies the booking model type of the property. Can be RTB (request to Book) or IB (instant booking). | enum | Required | Default: IB. You can check the eligibility criteria. | TPA_Extensions > RTB | |
> invoice_settings | Details of the company that owns/manages the property | object | Optional | Invoice settings cannot be updated during the billing period from 1st to 7th day of the month. | ||
legal_name | Legal name of the company | string | Optional | |||
contact_person | Full name of the contact person | string | Optional | You need to setup if you want property to go Open/Bookable. | ContactInfos > ContactInfo > Name | |
address | Company address | string | Optional | You need to setup if you want property to go Open/Bookable. | ContactInfos > ContactInfo > Addresses > AddressLine | |
country_code | Country Code. Should be valid ISO code. | string | Optional | You need to setup if you want property to go Open/Bookable. | ContactInfos > ContactInfo > Addresses > CountryName | |
city | City name. | string | Optional | You need to setup if you want property to go Open/Bookable. | ContactInfos > ContactInfo > Addresses > CityName | |
postal_code | Postal/Zip code | string | Optional | You need to setup if you want property to go Open/Bookable and should have valid postal/zip code for the country code. | ContactInfos > ContactInfo > Addresses > PostalCode | |
state | State. | string | Optional | ContactInfos > ContactInfo > Addresses > StateProv > StateCode | ||
notification_channel | The channel how company should be notified invoice related mails. Can be one of: POSTAL_MAIL or EMAIL. | enum | Optional | |||
>> brazil_tax_details | You can indicate additional settings for Brazilian properties, issued by the Brazilian tax authority. Used for invoicing. | object | Optional | You need to setup brazil tax details if you want property in Brazil to go Open/Bookable. | ||
tax_payer_number_type | Specifies whether the identifying number belongs to a company or a private individual. | string | Optional | TPA_Extensions > InvoiceDetails > InvoiceTaxType > Type | ||
tax_payer_number | The identifying number. CNPJ = 14 digits. CPF = 11 digits. | string | Optional | TPA_Extensions > InvoiceDetails > InvoiceTaxNumber > Code | ||
city_hall_id | The 8-digit ID for the city hall which issued the CNPJ or CPF number | string | Optional | TPA_Extensions > InvoiceDetails > CityHallInfo > ID | ||
email | Email address of invoice recipient. | string | Optional | TPA_Extensions > InvoiceDetails > InvoiceAddress > Email |
Response body
Click to view the response body example:
{ "property_settings":{ "success":true }, "renovation":{ "success":true }, "standard_phrases":{ "success":true }, "bed_linen_policy":{ "success":true }, "child_policies":{ "success":true }, "age_buckets":{ "success":true }, "quiet_hours":{ "success":true }, "booking_model":{ "success":true }, "cancellation_exceptions":{ "success":true }, "french_tax_details":{ "success":true }, "damage_policy":{ "success":true } }
Error samples
When using the Property Settings API, you can encounter two different type of error responses:
- API level validation error, and
- Business logic or system error
API validation error
The API validation type error is handled at the API level. You may encounter this response if you fail to provide the required field or when the API encounters incorrect data type in the request body.
For example when setting pets without required pets_allowed
field, the API returns the following response:
{ "warnings": [], "errors": [ { "message": "Required field missing", "code": 321, "details": { "fields": [ "$.pets.pets_allowed" ] }, "description": "must not be null" } ], "meta": { "ruid": "..." } }
Business logic error
You may encounter a business logic error when the API validates your request against Booking.com business rules and it fails. For example, when setting child policies with no rooms may result in the following error:
{ "data": { "child_policies": { "success": false } }, "warnings": [ { "message": "Invalid value", "code": 320, "description": "None of the rooms have children occupancy set. Therefore, AcceptedGuestType for the property is set to AdultOnly. Call OTA_HotelInvNotif to increase children occupancy in rooms to allow children." } ], "errors": [], "meta": { "ruid": "..." } }
Retrieving property settings
GET
https://supply-xml.booking.com/property-api/properties/{propertyID}/settings
Use the GET property-api
endpoint along with the property ID to retrieve the property settings details.
Path parameter
The following table describes the elements you can add in the path:
Value | Description | Type | Required/ Optional | Notes |
---|---|---|---|---|
{property ID } value | Specify the unique ID of the property to retrieve its details. | integer | Required |
Response body parameters
To know more about the response body parameters, see the open API specification of the Property API settings
endpoint.
Response body example
Click to view the full response.
{ "data": { "property_settings": { "require_cvc": true, "curfew": { "start": "18:00", "end": "09:00" }, "require_booker_address": true, "require_booker_phone_number": true, "age_restriction": { "min": 18, "max": 99 }, "auto_replenish": true, "replenish_closed_rooms": true, "long_stay": { "max_length_of_stay": 45 }, "pricing_type": "Standard", "allow_smoking": true, "view_cc_details": true }, "pets": { "pets_allowed": "PETS_NOT_ALLOWED", "pets_price_type": "FREE" }, "damage_policy": { "amount": 80.0, "currency": "EUR", "policy_type": "HANDLED_BY_BOOKING_COM", "damage_programme_terms_agreed": true }, "standard_phrases": [ { "name": "GuestIdentification", "enabled": true } ], "quiet_hours": { "start": "22:00", "end": "06:00" }, "renovation": { "renovation_from": "2014-01-01", "renovation_until": "2014-01-10" }, "bed_linen_policy": { "amount": 100.0 }, "accepted_payment_types": { "codes": [ 1, 2, 55 ] }, "french_tax_details": { "category_id": 0, "nature_id": 0, "declare_revenue": true, "has_vat": true, "registered_in_rcs": true }, "cancellation_exceptions" : { "grace_period": { "enabled": true, "after_booking": "HOUR_1" }, "advance_cancellation": { "enabled": true, "before_check_in": "WEEKS_4" } }, "age_buckets": [ { "min_age": 1, "max_age": 10 } ], "children_policies": { "allow_children": true, "min_age": 0, "policy_rules": [ { "rule_type": "EXISTING_BED", "from_age": 0, "to_age": 0, "price_type": "FREE", "price_mode": "PER_STAY", "price": 0 } ] }, "invoice_settings": { "legal_name": "string", "contact_person": "string", "address": "string", "state": "string", "notification_channel": "string", "payment_method": "string", "country_code": "string", "city": "string", "postal_code": "string", "brazil_tax_details": { "tax_payer_number_type": "string", "tax_payer_number": "string", "city_hall_id": "string", "email": "string" } }, "booking_model": { "type": "IB" } }, "warnings": [ { "message": "string", "code": "string", "details": {} } ], "errors": [ { "message": "string", "code": "string", "details": {} } ], "meta": { "ruid": "string" } }
Retrieving terms and conditions for damage programme
GET
https://supply-xml.booking.com/property-api/legal/damage-programme/terms
Use the GET property-api
endpoint along with the language code to retrieve the terms and conditions for enrolling into the damage programme with Booking.com.
Header parameter
The following table describes the elements you can add in the header:
Header | Description | Type | Required/ Optional | Notes |
---|---|---|---|---|
Accept-Version | Specify the version number to get the API functionality specific to that version. | string | Optional | Currently supports the value: 1.0 |
Query parameter
The following table describes the elements you can add in the query:
Value | Description | Type | Required/ Optional | Notes |
---|---|---|---|---|
language_code | Specify the language code in which you want the terms to be returned in. | Accepts the values listed under BCL. | Required |
Response body parameters
To know more about the response body parameters, see the open API specification of the Property API settings
section.
Quick Actions
→ To create and manage property, see Property API.