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:

Create new cancellation policies on the property level.
Modify the penalty conditions of an existing cancellation policy.
Retrieve cancellation policy details.

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_cancellation_fee_begins`: 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: - `default`: 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 default 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. However, the policy ID remains unchanged across the policy's lifespan.
	`GroupName`	Specifies the internal policy name. GroupName and Policy ID are unrelated.	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: - `default`: 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_cancellation_fee_begins`: 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="default"/>
            <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. Note that the policy ID remains unchanged.

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 = "default"
Cancellation policy 2 -- PolicyCode="49" , GuaranteePayment Required = "false", NoShow Penalty = "default"
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_cancellation_fee_begins", 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_cancellation_fee_begins`: 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: - `default`: 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_cancellation_fee_begins">
            </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_cancellation_fee_begins">
                <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	The policy ID remains unchanged across the policy's lifespan.
	`GroupName`	Specifies the internal policy name. Policy ID and GroupName are unrelated.	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: - `default`: 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_cancellation_fee_begins`: 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_cancellation_fee_begins">
                <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	The policy ID remains unchanged across the policy's lifespan.
	`GroupName`	Specifies the internal policy name. Policy ID and GroupName are unrelated.	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: - `default`: 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_cancellation_fee_begins`: 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.