Home

Beta version

This API endpoint is currently in beta. Make sure to direct any questions during the beta phase to your Booking.com contact person via the appropriate channels.

Managing property settings

Use the property settings endpoint of the Property API (property-api) to create, update, remove and retrieve property settings.

Use the Property-API settings endpoint to:

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 allowance, grace period, quiet hours, renovation and few others.

You can set 1 or multiple settings in 1 request.

After successfully processing the request, the endpoint returns a granular response for each setting group that you passed in the request.

For example, when you pass the following property settings group:

{
  "property_settings": {
    "no_smoking": true
  },
  "renovation": {
    "enabled": true,
    "start": "2024-01-02",
    "end": "2024-10-10"
  },
  "standard_phrases": [
    {
      "name": "NoHenStagParty",
      "enabled": 1
    }
  ]
}

The API returns the following response on successful completion:

{
  "data": {
    "property_settings": {
      "success": true
    },
    "renovation": {
      "success": true
    },
    "standard_phrases": {
      "success": true
    }
  },
  "warnings": [],
  "errors": [],
  "meta": {
    "ruid": "..."
  }
}

API validations

This section contains any validations that the API enforces when processing the request.

Make sure your request meets the following validations, failing which the API returns an error:

  • Property Settings API can update only an existing property. Therefore, to use this API, you will need create property first. Please check Property API.
  • Curfew and quiet hours start and end time should follow the following time format: HH:mm.
  • Renovation dates start and end should follow the following date format: yyyy-mm-dd.
  • Age buckets can't have more than 3 values and cannot overlap with each other.
  • invoice_settings should have valid postal/zip code for the country code.

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
Accept-Version Specify the version number to get the API functionality specific to that version. string optional Currently supports the value: 1.0

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:

{
  "property_settings": {
    "no_cvc": true,
    "view_cc_details": true,
    "curfew": {
      "enabled": true,
      "start": "18:00",
      "end": "09:00"
    },
    "always_require_booker_address": true,
    "always_require_booker_contact_number": true,
    "age_restriction": {
      "enabled": true,
      "min": 1,
      "max": 99
    },
    "auto_replenish": true,
    "replenish_closed_rooms": true,
    "prevent_likely_to_be_cancelled_bookings": true,
    "long_stay": {
      "enabled": true,
      "max_length_of_stay": 45
    },
    "pricing_type": "Standard",
    "no_smoking": true
  },
  "pets": {
    "pets_allowed": "PETS_NOT_ALLOWED",
    "pets_price_type": "FREE"
  },
    "damage_policy": {
        "amount": 90,
        "policy_type" : "DAMAGE_DEPOSIT",
        "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,
    "renovation_from": "2014-01-01",
    "renovation_until": "2014-01-10"
  },
  "hotel_chain_bed_linen": {
    "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
  },
  "grace_period": {
    "enabled": true,
    "hours_after_booking": 1,
    "weeks_before_check_in": 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 response elements:

Object Attribute Description Type Notes
> property_settings Contains multiple various settings related to the property. object
no_cvc Specifies whether the guest needs to provide CVC details for the booking. boolean
view_cc_details Specifies whether a trusted property can view the guest's credit card details. boolean
always_require_booker_address Specifies whether the guests must provide a contact address. boolean
always_require_booker_contact_number Specifies whether the guests must provide a contact telephone number. boolean
auto_replenish Specifies if property is enabled to auto-replenish room inventory when there is a cancellation. boolean
replenish_closed_rooms Reopen closed rooms after a cancellation. boolean
prevent_likely_to_be_cancelled_bookings Specifies whether to enable the feature that prevents bookings that are likely to be cancelled. boolean
pricing_type Specifies the property's pricing type. Can be Standard, LOS or OBP. Default value is Standard. For more information, see pricing types. enum
no_smoking Specifies whether the property allows smoking. boolean
>> curfew Contains curfew settings for the property. object
enabled Specifies whether the property has curfew time enabled. boolean Required
start Time when curfew starts. Accepts the format: HH:MM. Only effective when enabled=true. boolean
end Time when curfew ends. Accepts the format: HH:MM. Only effective when enabled=true. boolean
>> age_restriction Contains whether there is an age limit to check-in. object
enabled Specify whether age restriction is enabled boolean Required
min Specifies the minimum allowed age for guests to check-in. Allowed age range: 18-99. Only effective when enabled=true. boolean
max Specifies the maximum allowed age for guests to check-in. Allowed age range: 18-99. Only effective when enabled=true. boolean
>> long_stay Contains whether property accepts a stay longer than 30 nights. object
enabled Specifies whether the property has a long stay option enabled. boolean Required
max_length_of_stay Specifies Time when curfew starts, accepted format is HH:MM. Only effective when enabled=true. boolean
> pets Contains settings related to pets allowance. object
pets_allowed 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
> damage_policy Contains settings related to damage policy. object
amount Specifies the amount on which the damage deposit or programme is applicable for double Required
currency Specifies the currency in which the claim and limit occurs. Default is Property Currency if not specified. optional
policy_type Specifies the policy that is applicable. Possible values are:
- NONE,
- DAMAGE_DEPOSIT and
- DAMAGE_PROGRAMME.		 enum required DAMAGE_DEPOSIT - Guests pay you a damage deposit directly. DAMAGE_PROGRAMME - 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 boolean optional
collection_mode Specifies how you would collect damage deposit. Possible values are:
- CASH,
- CREDIT_CARD,
- PAYPAL,
- BANK_TRANSFER and
- OTHER.		 enum optional
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
return_mode Specifies how you would return the damage deposit. Possible values are:
- CASH,
- CREDIT_CARD,
- PAYPAL,
- BANK_TRANSFER and
- OTHER.		 enum optional
return_when Specifies when you would return the damage deposit. Possible values are:
- ON_CHECKOUT,
- WITHIN_7_DAYS and
- WITHIN_14_DAYS.		 enum optional
> 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
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
enabled Specifies whether the property has quiet hours enabled. boolean Required
start Specifies the quiet hours start time. Accepts the format" HH:mm string
end Specifies the quiet hours end time. Accepts the format: HH:mm string
> renovation Contains settings related to renovation dates. object
enabled Specifies whether renovation dates are enabled. boolean Required
renovation_from Specifies the renovation start date. Accepts the format: yyyy-mm-dd. string
renovation_until Specifies the renovation end date. Accepts the format: yyyy-mm-dd. string
> hotel_chain_bed_linen 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
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
> accepted_payment_types Contains settings related to payment methods. object
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
> french_tax_details Contains settings related to tax details. object
category_id Contains a number - city tax category ID. You can retrieve available categories using the /xml/citytaxcategory call. string
nature_id Contains a number - nature category ID. You can retrieve available categories using /xml/citytaxcategory call. string
declare_revenue Specifies whether the property declares revenues as professional for direct tax purposes. boolean Required
has_vat Specifies whether the property has a registered VAT for this activity. boolean Required
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
> grace_period Contains settings related to tax details. object
enabled Specifies whether the property has a grace period enabled. boolean Required
hours_after_booking Grace period - amount of hours after booking when free cancellation is available. Can be one of the values: 0, 1, 4 or 24. integer
weeks_before_check_in Advance cancellation - amount of weeks before check-in when free cancellation is available. Can be one of the values: 0, 4, 8 or 12. integer
> 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 You must at least create one, but can create up to three age buckets per property. Each age bucket contains a minimum and maximum age, where the maximum age is inclusive.
min_age Specifies the minimum age for the age bucket. integer Required
max_age Specifies the maximum age for the age bucket. integer Required
> 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
allow_children Specifies whether the property admits adults and children, or only adults. integer
min_age Specifies the minimum age of children allowed to stay at the property. Applies only when allow_children = true. integer
>> policy_rules You can indicate additional rules for extra beds or cribs. array of objects
rule_type Specifies the rule type for which this rule applies. Possible values are:
- EXISTING_BED
- EXTRA_BED
- CRIB).		 enum
from_age Specifies the minimum age for the children policy to apply. In combination with to_age it becomes an age range. integer
to_age Specifies the maximum age for the children policy to apply. integer
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
price_mode Specifies the unit of time on which the charge is calculated. Can be PER_NIGHT or PER_STAY. enum
price Specifies the amount charged in the [country's local currency.][b_xml-countrycurrencies] double
> booking_model You can indicate that property can have request to book option object
type Specifies the booking model type of the property. Can be RTB (request to Book) or IB (instant booking). enum Required
> invoice_settings Details of the company that owns/manages the property object
legal_name Legal name of the company string
contact_person Full name of the contact person string
address Company address string
country_code Country Code. Should be valid ISO code. string
city City name. string
postal_code Postal/Zip code string
state State. string
notification_channel The channel how company should be notified invoice related mails. Can be one of: POSTAL_MAIL or EMAIL. enum
>> brazil_tax_details You can indicate additional settings for Brazilian properties, issued by the Brazilian tax authority. Used for invoicing. object
tax_payer_number_type Specifies whether the identifying number belongs to a company or a private individual. string
tax_payer_number The identifying number. CNPJ = 14 digits. CPF = 11 digits. string
city_hall_id The 8-digit ID for the city hall which issued the CNPJ or CPF number string
email Email address of invoice recipient. string

Response body

Click to view the response body example:

{
  "property_settings":{
    "success":true
  },
  "renovation":{
    "success":true
  },
  "standard_phrases":{
    "success":true
  },
  "hotel_chain_bed_linen":{
    "success":true
  },
  "child_policies":{
    "success":true
  },
  "age_buckets":{
    "success":true
  },
  "quiet_hours":{
    "success":true
  },
  "booking_model":{
    "success":true
  },
  "grace_period":{
    "success":true
  },
  "french_tax_details":{
    "success":true
  },
  "damage_policy":{
    "success":true
  }

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.

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

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's settings endpoint.

Response body example

Click to view the full response. 

{
  "data": {
    "property_settings": {
      "no_cvc": true,
      "curfew": {
        "start": "18:00",
        "end": "09:00"
      },
      "always_require_booker_address": true,
      "always_require_booker_contact_number": true,
      "age_restriction": {
        "min": 1,
        "max": 99
      },
      "auto_replenish": true,
      "replenish_closed_rooms": true,
      "prevent_likely_to_be_cancelled_bookings": true,
      "long_stay": {
        "max_length_of_stay": 45
      },
      "pricing_type": "Standard",
      "no_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": "DAMAGE_PROGRAMME",
            "damage_programme_terms_agreed": true
        },
    "standard_phrases": [
      {
        "name": "GuestIdentification",
        "enabled": true
      }
    ],
    "quiet_hours": {
      "start": "string",
      "end": "string"
    },
    "renovation": {
      "renovation_from": "2014-01-01",
      "renovation_until": "2014-01-10"
    },
    "hotel_chain_bed_linen": {
      "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
    },
    "grace_period": {
      "hours_after_booking": 0,
      "weeks_before_check_in": 0
    },
    "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"
      },
      "contract_group": 0
    },
    "booking_model": {
      "type": "IB"
    }
  },
  "warnings": [
    {
      "message": "string",
      "code": "string",
      "details": {}
    }
  ],
  "errors": [
    {
      "message": "string",
      "code": "string",
      "details": {}
    }
  ],
  "meta": {
    "ruid": "string"
  }

Quick Actions


→ To create and manage property, see Property API.

Is this page helpful?    Yes   |    No