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 policies

The Policies API enables you to create and manage cancellation policies on the property level. You can:

Creating a cancellation policy

POST
https://supply-xml.booking.com/policy-api/properties/{property_id}/policies

This endpoint enables you to create a new cancellation policy for a property. You can create a maximum of 7 cancellation policies for properties.

Use this endpoint to create one cancellation policy at a time. To create more than 1 cancellation policy, run the endpoint multiple times.

Cannot create duplicate cancellation policies

You cannot create cancellation policies with the same combination of penalty code, guarantee payment and no show penalty conditions. However, you can use the same penalty code to create multiple cancellation policies with one or more combinations of these conditions.

Path parameters

The following table describes the elements you must specify in the path:

Element Description Type Required/
Optional
Notes
property_id Specifies the unique ID of the property to which the cancellation policy applies. integer required You must have permission to edit the property.

Request body parameters

The following table describes the elements you must add in the request body:

Element Attribute Description Type Required/
Optional
Notes
Request Root element object required
> Policies Contains the cancellation policy information you want to create for a property. object required There is a limit to the total number of cancellation policies you can create, that is, 7 for properties.
>> Policy Contains cancellation, guarantee payment and no show penalty fees for the policy. object required For more information on cancellation, guarantee payment and noshow penalty conditions, see Understanding cancellation policy penalty conditions.
type Specifies the policy type. enumerated string required Currently, the API supports only Cancellation.
>>> CancelPenalty Contains the details of the cancellation penalty assigned to the policy. object required
PolicyCode Specifies the Booking.com cancellation code that suits your business needs. integer required For a full list of cancellation codes and their descriptions, see the cancellation policy codes.
>>> GuaranteePayment Contains guarantee payment details. object required Certain penalty codes accept only specific combinations of Required and EffectiveFrom values. For example, a non-refundable penalty code must have the Required attribute always set to true and the fully-flexible penalty code must have the Required attribute always set to false. Except for the penalty codes specified in the Penalty code and guarantee payment matrix, you have the freedom to specify any guarantee payment value for all other penalty codes.
Required Indicates whether a guarantee payment is mandatory. boolean required Possible values are:
- true: Guarantee payment required
- false: Guarantee payment is not required
For CancelPenalty PolicyCode= 1,152,166 and 168, see the Penalty code and guarantee payment matrix.
EffectiveFrom Specifies when the guarantee payment is charged. enumerated string mandatory only when Required = "true" Possible values are:
- after_reservation_is_made: Use if you want the guests to make a payment immediately after reservation.
- after_free_cancellation_ends: Use if you want the guests to make a payment after the free cancellation window has closed.
If Required = "false", then any value provided here is ignored.
For CancelPenalty PolicyCode = 1, 166 and 168, see the Penalty code and guarantee payment matrix.
>>> NoShowPolicy Contains the no show penalty details. object optional
Penalty Specifies the penalty charged in case the guest does not turn up for the reservation. enumerated string optional Possible values are:
- cancellation_penalty: Use if you want the no show penalty to follow the cancellation fee.
- total_price: Use if you want the no show penalty to equal the total reservation price.
By default, the API creates a policy with a no show penalty that equals the cancellation penalty.

Penalty code and guarantee payment matrix

The following table contains cancellation policy codes that need specific GuaranteePayment Required and EffectiveFrom values.

Cancel Penalty Code Guarantee payment required Guarantee payment EffectiveFrom Notes
1 true after_reservation_is_made Non-refundable policy.
152 false Not applicable Fully flexible policy.
166 true after_reservation_is_made Partially refundable policy.
168 true after_reservation_is_made Partially refundable policy.

Request body example

The following request body example creates a cancellation policy as shown in the Response body section:

PolicyCode="55": The guest can cancel free of charge until 2 days before arrival. The guest will be charged 50% of the total price if they cancel in the 2 days before arrival. In this case, until 2 days before the arrival date. If the guests do not turn up for the reservation, then they are charged the total stay price.
Alternatively, you can set NoShowPolicy Penalty to cancellation_penalty to charge the guests the same as the cancellation fee.

<Request>
   <Policies>
      <Policy Type="Cancellation">
         <CancelPenalty PolicyCode="55" />
         <GuaranteePayment Required="true" EffectiveFrom="after_reservation_is_made">
         </GuaranteePayment>
         <NoShowPolicy Penalty="total_price" />
      </Policy>
   </Policies>
</Request>

Response body

<?xml version='1.0' encoding='UTF-8'?>
<Response>
 <Success/>
 <Policies>
  <Policy Id="342546364" GroupName="partially refundable" Type="Cancellation">
   <CancelPenalty PolicyCode="55">
    <PenaltyDescription>
     <text>The guest can cancel free of charge until 2 days before arrival. The guest will be charged 50% of the total price if they cancel in the 2 days before arrival. If the guest doesn't show up, they will be charged the total price of the reservation.</text>
    </PenaltyDescription>
   </CancelPenalty>
   <NoShowPolicy Penalty="total_price"/>
   <GuaranteePayment Required="true" EffectiveFrom="after_reservation_is_made">
    <TPA_Extensions>
     <Description>The guest will be charged a prepayment of 50% of the total price after reservation.</Description>
    </TPA_Extensions>
   </GuaranteePayment>
  </Policy>
 </Policies>
</Response>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YYpJvAsQ/OdctGdjkiDQ+B+dNlGSmheRnEVdvjxt7REIIRr8gNYNj0Gn3CLTKeGYjg==] -->

Response body elements

The following table describes the response elements:

Element Attribute Description Type Notes
Response Root element object
> Policies Contains the details of the cancellation policy created for the property. object
>> Policy Contains the cancellation, guarantee payment, and no show penalty details for each cancellation policy. object
Id Specifies the uniquely identifiable policy ID. integer Use this value to make subsequent edits to the policy.
GroupName Specifies the internal policy name. string The group name does not hold any logic and is randomly assigned, except for 'general' which indicates it is the default policy. However, you can use a policy's group name to identify it in the extranet. In future, GroupName may get deprecated.
Type Specifies the policy type. enumerated string Currently, the API supports only Cancellation.
>>> CancelPenalty Contains the details of the cancellation penalty assigned to the policy. object
PolicyCode Specifies the Booking.com cancellation code that was included in the request. integer
>>>> PenaltyDescription Contains the cancellation penalty description. object
>>>>> text Specifies the cancellation penalty in natural language. string Currently, the API supports description text in English.
>>> NoShowPolicy Contains the no show penalty details. object
Penalty Specifies the penalty charged in case the guest does not turn up for the reservation. enumerated string Possible values are:
- cancellation_penalty: Use if you want the no show penalty to follow the cancellation fee.
- total_price: Use if you want the no show penalty to equal the total reservation price.
>>> GuaranteePayment Contains the guarantee payment details. object
Required Specifies whether a guarantee payment is mandatory. boolean Possible values are:
- true: Guarantee payment required
- false: Guarantee payment is not required
EffectiveFrom Specifies when the guarantee payment is charged. enumerated string Possible values are:
- after_reservation_is_made: Enforces guests to make a payment immediately after reservation.
- after_free_cancellation_ends: Enforces guests to make a payment after the free cancellation window has closed.
>>>> TPA_Extensions Contains the guarantee payment description. object
>>>>> Description Specifies the guarantee payment in natural language. string Currently, the API supports description text in English.
ruid Specifies the unique request ID. string You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong.
Success Specifies the success status of the request. object
errors Lists potential errors. This can help in understanding what went wrong with your request. array This can help in understanding what went wrong with your request. For a list of errors/warnings and how to troubleshoot them, see Troubleshooting errors.
warnings Lists potential warnings. This can help you improve your requests. array This can help improve your requests in future.

Creating a duplicate cancellation policy returns an error

When creating a duplicate cancellation policy with the same combination of penalty code, guarantee payment and no show penalty conditions, the API returns an error along with the details of the existing cancellation policy.

<?xml version='1.0' encoding='UTF-8'?>
<Response>
    <Policies>
        <Policy Id="341337682" GroupName="general" Type="Cancellation">
            <CancelPenalty PolicyCode="568"/>
            <NoShowPolicy Penalty="cancellation_penalty"/>
            <GuaranteePayment Required="false" EffectiveFrom="after_reservation_is_made"/>
            <Tags>
                <Default/>
            </Tags>
        </Policy>
    </Policies>
    <Errors>
        <Error Code="DUPLICATE_POLICY" ShortText="Cannot have 2 policies with the same cancellation and prepayment codes">
            <Details>
                <PolicyCode>341337682</PolicyCode>
            </Details>
        </Error>
    </Errors>
</Response>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9Yc2VQEtEQcWis2P7po9uf/HW/V97Zg8yxXcJRBupSbBiP1BtpRH5az5Fe10g+nziEQ==] --

Changing policy details

POST
https://supply-xml.booking.com/policy-api/properties/{property_id}/policies/{policy_id}

Use this endpoint to change the existing penalty conditions of a cancellation policy.

Editing cancellation policies assigned to a roomrate

You can change the penalty conditions for any cancellation policy, including a policy that is assigned to a roomrate. Once changed, the new penalty conditions are applied to the roomrate. The API doesn't respond with a warning when a cancellation policy that is already assigned to a roomrate is modified.

Let's consider that a property already has the following 3 cancellation policies:

  • Cancellation policy 1 -- PolicyCode="152", GuaranteePayment Required = "false", NoShow Penalty = "cancellation_penalty"
  • Cancellation policy 2 -- PolicyCode="49" , GuaranteePayment Required = "false", NoShow Penalty = "cancellation_penalty"
  • Cancellation policy 3 -- PolicyCode="1", GuaranteePayment Required = "true" EffectiveFrom="after_reservation_is_made", NoShow Penalty = "total_price"

You can use the above endpoint to change the cancellation code of the cancellation policy 2 to, let's say, PolicyCode="45" (Flexible - 14:00 on arrival day) , GuaranteePayment Required = "true" EffectiveFrom="after_free_cancellation_ends", NoShow Penalty = "total_price".

Make sure to specify the appropriate policy ID to edit a cancellation policy. To find the unique policy ID, run the GET policies endpoint.

Path parameters

The following table describes the elements you must specify in the path:

Element Description Type Required/
Optional
Notes
property_id The unique ID of the property to which the cancellation policy applies. integer required You must have permission to edit the property.
policy_id The unique ID of the cancellation policy to edit. integer required You must have permission to edit the property.

Request body parameters

The following table describes the elements you must add in the request body:

Element Attribute Description Type Required/
Optional
Notes
Request Root element. object required
> Policies Contains the cancellation policy details to update a specific policy. object required
>> Policy Contains the cancellation, guarantee payment and no show penalty fees for the policy. object required For more information on cancellation, guarantee payment and noshow penalty fees, see Understanding cancellation policy penalty conditions.
type Specifies the policy type. enumerated string required Currently, the API supports only Cancellation.
>>> CancelPenalty Contains the details of the cancellation penalty assigned to the policy. object required
PolicyCode Specifies the Booking.com cancellation code that suits your business needs. integer required For a full list of cancellation codes and their descriptions, see the cancellation policy codes.
>>> GuaranteePayment Contains guarantee payment details. object required Certain penalty codes accept only specific combinations of Required and EffectiveFrom values. For example, a non-refundable penalty code must have the Required option always set to true and the fully-flexible penalty code must have the Required attribute always set to false. Except for the penalty codes specified in the Penalty code and guarantee payment matrix, you have the freedom to specify any guarantee payment value for all other penalty codes.
Required Specifies whether a guarantee payment is mandatory. boolean required Possible values are:
- true: Guarantee payment required
- false: Guarantee payment is not required
For CancelPenalty PolicyCode = 1,152,166 and 168, see the Penalty code and guarantee payment matrix.
EffectiveFrom Specifies when the guarantee payment is charged. enumerated string mandatory only when Required = "true" Possible values are:
- after_reservation_is_made: Use if you want the guests to make a payment immediately after reservation.
- after_free_cancellation_ends: Use if you want the guests to make a payment after the free cancellation window has closed.
If Required = "false", then any value provided here is ignored.
For CancelPenalty PolicyCode= 1, 166 and 168, see the Penalty code and guarantee payment matrix.
>>> NoShowPolicy Contains the no show penalty details. object optional
Penalty Specifies the penalty charged in case the guest does not turn up for the reservation. enumerated string optional Possible values are:
- cancellation_penalty: Use if you want the no show penalty to follow the cancellation fee.
- total_price: Use if you want the no show penalty to equal the total reservation price.
By default, the API creates a policy with a no show penalty that equals the cancellation penalty.

Request body example

The following is a request body example where you can modify a cancellation policy's penalty conditions:

<Request>
    <Policies>
        <Policy Type="Cancellation">
            <CancelPenalty PolicyCode="45" />
            <GuaranteePayment Required="true" EffectiveFrom="after_free_cancellation_ends">
            </GuaranteePayment>
            <NoShowPolicy Penalty="total_price" />
        </Policy>
    </Policies>
</Request>

Response body example

<?xml version='1.0' encoding='UTF-8'?>
<Response>
    <Success/>
    <Policies>
        <Policy Id="342546377" GroupName="special conditions 2" Type="Cancellation">
            <CancelPenalty PolicyCode="45">
                <PenaltyDescription>
                    <text>The guest can cancel free of charge until 14:00 on the day of arrival. The guest will be charged 50% of the total price if they cancel after 14:00 on the day of arrival. If the guest doesn't show up, they will be charged the total price of the reservation. </text>
                </PenaltyDescription>
            </CancelPenalty>
            <NoShowPolicy Penalty="total_price"/>
            <GuaranteePayment Required="true" EffectiveFrom="after_free_cancellation_ends">
                <TPA_Extensions>
                    <Description>The guest will be charged a prepayment of 50% of the total price after 14:00 on the day of arrival.</Description>
                </TPA_Extensions>
            </GuaranteePayment>
        </Policy>
    </Policies>
</Response>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YdeUx1ir1qlOvYo5I5xc56iKQJbXCr6IJtAiYYsytOvMji/5UbFFD4dFStbg0mqYyQ==] -->

Response body elements

The following table describes the response elements:

Element Attribute Description Type Notes
Response Root element. object
> Policies Contains the details of the cancellation policy created for the property. object
>> Policy Contains the cancellation, guarantee payment, and no show penalty details for each cancellation policy. object
Id Specifies the uniquely identifiable policy ID. integer
GroupName Specifies the internal policy name. string The group name does not hold any logic and is randomly assigned, except for 'general' which indicates it is the default policy. However, you can use a policy's group name to identify it in the extranet. In future, GroupName may get deprecated.
Type Specifies the policy type. enumerated string Currently, the API supports only Cancellation.
>>> CancelPenalty Contains the details of the cancellation penalty assigned to the policy. object
PolicyCode Specifies the Booking.com cancellation code that was included in the request. integer
>>>> PenaltyDescription Contains the cancellation penalty description. object
>>>>> text Specifies the cancellation penalty in natural language. string Currently, the API supports description text in English.
>>> NoShowPolicy Contains the no show penalty details. object
Penalty Specifies the penalty charged in case the guest does not turn up for the reservation. enumerated string Possible values are:
- cancellation_penalty: Use if you want the no show penalty to follow the cancellation fee.
- total_price: Use if you want the no show penalty to equal the total reservation price.
>>> GuaranteePayment Contains the guarantee payment details. object
Required Specifies whether a guarantee payment is mandatory. boolean Possible values are:
- true: Guarantee payment required
- false: Guarantee payment is not required
EffectiveFrom Specifies when the guarantee payment is charged. enumerated string Possible values are:
- after_reservation_is_made: Enforces guests to make a payment immediately after reservation.
- after_free_cancellation_ends: Enforces guests to make a payment after the free cancellation window has closed.
>>>> TPA_Extensions Contains the guarantee payment description. object
>>>>> Description Specifies the guarantee payment in natural language. string Currently, the API supports description text in English.
ruid Specifies the unique request ID. string You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong.
Success Specifies the success status of the request. object
errors Lists potential errors. This can help in understanding what went wrong with your request. array This can help in understanding what went wrong with your request. For a list of errors/warnings and how to troubleshoot them, see Troubleshooting errors.
warnings Lists potential warnings. This can help you improve your requests. array This can help improve your requests in future.

Retrieving policy details

GET
https://supply-xml.booking.com/policy-api/properties/{property_id}/policies

Use this endpoint to retrieve all the existing cancellation policies of a property.

Path parameters

The following table lists the path parameters in the request:

Parameter Description Type Required/Optional Notes
property_id Specify the property ID to view all the cancellation policies created for it. integer required You can only specify one property ID per call.

Request body example

This request has no body parameters. The property ID is specified in the path.

Response body example

The following is a successful response body example:

<?xml version='1.0' encoding='UTF-8'?>
<Response>
    <Policies>
        <Policy Id="341337682" GroupName="general" Type="Cancellation">
            <CancelPenalty PolicyCode="43">
                <PenaltyDescription>
                    <text>The guest can cancel free of charge until 14:00 on the day of arrival. The guest will be charged the cost of the first night if they cancel after 14:00 on the day of arrival. If the guest doesn't show up, they will be charged the total price of the reservation.</text>
                </PenaltyDescription>
            </CancelPenalty>
            <NoShowPolicy Penalty="total_price"/>
            <GuaranteePayment Required="true" EffectiveFrom="after_free_cancellation_ends">
                <TPA_Extensions>
                    <Description>The guest will be charged a prepayment of the cost of the first night after 14:00 on the day of arrival.</Description>
                </TPA_Extensions>
            </GuaranteePayment>
            <Tags>
                <Default/>
            </Tags>
        </Policy>
        <Policy Id="341337684" GroupName="non refundable" Type="Cancellation">
            <CancelPenalty PolicyCode="1">
                <PenaltyDescription>
                    <text>The guest will be charged the total price of the reservation if they cancel at any time. If the guest doesn't show up, they will be charged the total price of the reservation.</text>
                </PenaltyDescription>
            </CancelPenalty>
            <NoShowPolicy Penalty="total_price"/>
            <GuaranteePayment Required="true" EffectiveFrom="after_reservation_is_made">
                <TPA_Extensions>
                    <Description>The guest will be charged a prepayment of the total price of the reservation at any time.</Description>
                </TPA_Extensions>
            </GuaranteePayment>
        </Policy>
    </Policies>
</Response>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YfVa0UDxWENgbrndLA72Iett82KnybF4RoaYlUrkCWX90ubm68zY3Nhwm4kPeKcIvQ==] -->

Response body elements

The following table describes the response elements:

Element Attribute Description Type Notes
Response Root element object
> Policies Contains the details of all the cancellation policies created for the property. array of Policy
>> Policy Contains the cancellation, guarantee payment, and no show penalty details for each cancellation policy. object
Id Specifies the unique policy ID. integer
GroupName Specifies the internal policy name. string The group name does not hold any logic and is randomly assigned, except for 'general' which indicates it is the default policy. However, you can use a policy's group name to identify it in the extranet. In future, GroupName may get deprecated.
Type Specifies the policy type. enumerated string Currently, the API supports only Cancellation.
>>> CancelPenalty Contains the details of the cancellation penalty assigned to the policy. object
PolicyCode Specifies the Booking.com cancellation code that was included in the request. integer For a list of all the available cancellation codes, see the cancellation policy codes.
>>>> PenaltyDescription Contains the cancellation penalty description. object
>>>>> text Specifies the cancellation penalty in natural language. string Currently, the API supports description text in English.
>>> NoShowPolicy Contains the no show penalty details. object
Penalty Specifies the penalty charged in case the guest does not turn up for the reservation. enumerated string Possible values are:
- cancellation_penalty: Use if you want the no show penalty to follow the cancellation fee.
- total_price: Use if you want the no show penalty to equal the total reservation price.
>>> GuaranteePayment Contains the guarantee payment details. object
Required Specifies whether a guarantee payment is mandatory. boolean Possible values are:
- true: Guarantee payment required
- false: Guarantee payment is not required
EffectiveFrom Specifies when the guarantee payment is charged. enumerated string Possible values are:
- after_reservation_is_made - Enforces guests to make a payment immediately after reservation.
- after_free_cancellation_ends: Enforces guests to make a payment after the free cancellation window has closed.
>>>> TPA_Extensions Contains the guarantee payment description. object
>>>>> Description Specifies the guarantee payment in natural language. string Currently, the API supports description text in English.
>>> Tags Contains the Default element. array
>>>> Default Indicates that the cancellation policy is the default policy. object When a roomrate is created without specifying a policy, the OTA_HotelProductNotif API assigns the policy with this tag to the roomrate.
ruid Specifies the unique request ID. string You can share this ID with Booking.com customer support when you run into an issue. This can help in understanding what went wrong.
errors Lists potential errors. array This can help in understanding what went wrong with your request. For a list of errors/warnings and how to troubleshoot them, see Troubleshooting errors.
warnings Lists potential warnings. array This can help improve your requests in future.

Quick Actions

→ To view roomrate details including the cancellation policy assigned to it, see Retrieving active roomrates.