Managing rate plans

Rate plans are labels or categories used to organise prices for a property.

How does Booking.com define a rate plan?

A rate plan is simply a name you use to organise prices. To add conditions such as a cancellation policy, prepayment policy, and meal plan, you must create a roomrate.

→ To learn more about rate plans, conditions, and roomrates, see basic definitions.

What falls under managing rate plans?

Managing rate plans involves the following actions:

Mapping room types and rate plans

To map your room types and rate plans to Booking.com's, you should use the retrieving roomrates endpoint. You could also use the retrieving room types and retrieving rate plans endpoints, but these contain less complete information. You could still use either to troubleshoot issues with mapping as needed.

What is the maximum number of rate plans the API supports?

You can create a maximum of 100 active rate plans for a property.

Creating a rate plan

POST https://supply-xml.booking.com/hotels/ota/OTA_HotelRatePlanNotif

The POST /ota/OTA_HotelRatePlanNotif request enables you to create a rate plan for your property.

Creating and updating

To create a rate plan you set RatePlanNotifType to New. If you want to update a rate plan, you set RatePlanNotifType to Overlay. In reality, updating a rate plan through this API is just renaming it.

Requirements for creating a room type

To create a rate plan on Booking.com, the following elements are required:

  • Property ID.
  • Rate plan name.

Body parameters

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

Element Attribute Description Type Required/Optional Notes
OTA_HotelRatePlanNotifRQ Contains the RatePlans array. object required
> Rateplans Contains the RatePlan objects. array required
HotelCode Specifies the unique ID of the property you create rate plans for. integer required
>> RatePlan Contains a Description object, which contains the name of the rate plan. object required
RatePlanNotifType Specifies the purpose of the request. enum required Possible values are New, Overlay, Activate, and Remove. You must use New to create a rate plan.
RatePlanID Specifies the rate plan ID you use in your system. string optional
>>> Description Contains the rate plan name. object required
Name Specifies the name of the rate plan. string required

Request body example

The following is a request body example:

<OTA_HotelRatePlanNotifRQ>
  <RatePlans HotelCode="6314570" >
    <RatePlan RatePlanNotifType="New" RatePlanID="123456">
      <Description Name="Summer Rate"/>
    </RatePlan>
  </RatePlans>
</OTA_HotelRatePlanNotifRQ>

Response body example

The following is a successful response body example:

<OTA_HotelRatePlanNotifRS>
    <RatePlanCrossRefs>
        <RatePlanCrossRef RequestRatePlanCode="123456" ResponseRatePlanCode="19617122"/>
    </RatePlanCrossRefs>
    <Success />
</OTA_HotelRatePlanNotifRS>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YWVEetwbMG/FMpzy/DyRiLnoKEGBZ3R] -->

The following is a response body example when the limit of 100 rate plans is reached:

<OTA_HotelRatePlanNotifRS>
    <Errors>
        <Error Type="10" Code="562" Status="NotProcessed" ShortText="Limit 100 of number of Rates has reached."/>
    </Errors>
</OTA_HotelRatePlanNotifRS>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YWVEetwbMG/FMpzy/QM5cwDyRiLnoKEGBZ3Rcslghlzsoierhgvs3efsve] -->

Response body parameters

The following table describes the response elements:

Element Attribute Description Type Notes
OTA_HotelRatePlanNotifRS Contains the response data. object
> RatePlanCrossRefs Contains the RatePlanCrossRef objects. array
>> RatePlanCrossRef Contains the mapping details in terms of your rate plan ID and Booking.com rate plan ID. object
RequestRatePlanCode Specifies your rate plan ID. string To see this, you must have specified the RatePlanID attribute in the RatePlan object of your request.
ResponseRatePlanCode Specifies the unique Booking.com ID of the created rate plan. integer
> warnings Contains potential warnings. These can help you improve your requests. array
> errors Contains potential errors. These can help you understand what went wrong with your request. array
> success Indicates the success of the request. object
ruid Specifies the unique ID of the request. string You can send this ID to Booking.com Connectivity Support team if you run into an issue. This can help to understand what went wrong.

Updating a rate plan

POST https://supply-xml.booking.com/hotels/ota/OTA_HotelRatePlanNotif

The POST /ota/OTA_HotelRatePlanNotif request enables you to create a rate plan for your property.

To update a rate plan, you must:

  • Set RatePlanNotifType to Overlay.
  • Specify the Booking.com rate plan ID in RatePlanCode.

→ To retrieve rate plans and their RatePlanCode, see retrieving rate plans.

Requirements for updating a rate plan

To create a rate plan on Booking.com, the following elements are required:

  • Property ID
  • Rate plan name
  • Rate plan ID

Body parameters

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

Element Attribute Description Type Required/Optional Notes
OTA_HotelRatePlanNotifRQ Contains the RatePlans array. object required
> Rateplans Contains the RatePlan objects. array required
HotelCode Specifies the unique ID of the property you update rate plans for. integer required
>> RatePlan Contains a Description object, which contains the name of the rate plan. object required
RatePlanNotifType Specifies what the exact purpose of the request is. enum required Possible values are New, Overlay, Activate, and Remove. You must set it to Overlay when updating a rate plan.
RatePlanID Specifies the rate plan ID you use in your system. string optional
RatePlanCode Specifies the unique ID of the rate plan you want to update. integer required
>>> Description Contains the rate plan name. object required
Name Specifies the name of the rate plan. string required

Request body example

The following is a request body example:

<OTA_HotelRatePlanNotifRQ>
  <RatePlans HotelCode="6314570" >
    <RatePlan RatePlanNotifType="Overlay" RatePlanCode="19617122" RatePlanID="123456">
      <Description Name="Summer non-refundable Rate"/>
    </RatePlan>
  </RatePlans>
</OTA_HotelRatePlanNotifRQ>

Response body example

The following is a successful response body example:

<OTA_HotelRatePlanNotifRS>
    <RatePlanCrossRefs>
        <RatePlanCrossRef RequestRatePlanCode="123456" ResponseRatePlanCode="19617122"/>
    </RatePlanCrossRefs>
    <Success />
</OTA_HotelRatePlanNotifRS>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YWVEetwbMG/FMpzy/DyRiLnoKEGBZ3R] -->

Response body parameters

The following table describes the response elements:

Element Description Type Notes
OTA_HotelRatePlanNotifRS Contains the response data. object
> warnings Contains potential warnings. These can help you improve your requests. array
> errors Contains potential errors. These can help you understand what went wrong with your request. array
> success Indicates the success of the request. object
ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.

Retrieving rate plans

POST https://supply-xml.booking.com/hotels/xml/rates

The POST /xml/rates request enables you to retrieve rate plans of a property, where you can further specify the following:

  • 1: Returns all rate plans.
  • 3: Returns all active rate plans.
  • 6: Returns all deactivated rate plans.

Body parameters

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

Element Description Type Required/Optional Notes
request Contains the request information. object required
> hotel_id Specifies the unique ID of the property you want to retrieve the rate plans for. integer required
> show_rates_status Specifies the code for the status of the rate plans you want to retrieve. integer optional Possible values are: 1 (All rate plans with active attribute), 3 (All active rate plans with active attribute set to active), and 6 (All deactivated rate plans with ctive attribute set to deactived).

Request body example

The following is a request body example:

<request>
   <hotel_id>6314570</hotel_id>
   <show_rates_status>1</show_rates_status>
</request>

Response body example

The following is a successful response body example:

<rates>
    <rate id="18045111" active="1" hotel_id="6314570" hotel_name="The Tech W">Non-refundable rate</rate>
    <rate id="19454895" active="1" hotel_id="6314570" hotel_name="The Tech W">Fully flexible</rate>
    <rate id="20275653" active="0" hotel_id="6314570" hotel_name="The Tech W">Standard rate</rate>
    <rate id="20442599" active="0" hotel_id="6314570" hotel_name="The Tech W" is_child_rate="1">basic rate extended</rate>
</rates>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YUPwiuucSHwvOzUg7gohCzo+vRzq/WYNpZcFinFyrhAIH9Bw+Rgsf2Km] -->

Response body parameters

The following table describes the response elements:

Element Attribute Description Type Notes
rates Contains the rate objects. object
> rate Contains the rate plan information. object
id Specifies the unique Booking.com ID of the rate plan. integer
active Indicates whether the rate plan is active or deactivated boolean Possible values are: 1 (active) and 0 (deactivated)
hotel_id Specifies the unique ID of the property you retrieved the rate plans for. integer
hotel_name Specifies the name of the property you retrieved the rate plans for. integer
is_child_rate Specifies whether the rate plan has a rate relation with a parent rate plan. boolean Possible value: 1 (Yes, rate plan is a child rate plan)
ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.

Deactivating a rate plan

POST https://supply-xml.booking.com/hotels/ota/OTA_HotelRatePlanNotif

The POST /ota/OTA_HotelRatePlanNotif request enables you to deactivate an active rate plan. To do so, you must:

  • Set RatePlanNotifType to Remove.
  • Specify the rate plan ID in RatePlanCode.

Removing is not deleting

You cannot delete rate plans, only deactivate them. This is important, because deactivated rate plans could still cause naming conflicts if you create a new rate plan with the same name.

Deactivating causes roomrates to be deactivated

If you deactivate a rate plan, all roomrates (products) you have created for a property with this rate plan become deactivated as well. This also means any inventory or availability is removed.

If you decide to activate a deactivated rate plan, you must both create roomrates and push inventory (availability) again.

Body parameters

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

Element Attribute Description Type Required/Optional Notes
OTA_HotelRatePlanNotifRQ Contains the RatePlans array. object required
> Rateplans Contains the RatePlan objects. array required
HotelCode Specifies the unique ID of the property. integer required
>> RatePlan Contains a Description object, which contains the name of the rate plan. object required
RatePlanNotifType Specifies what the exact purpose of the request is. enum required Possible values are New, Overlay, Activate, and Remove. You must set it to Remove to deactivate a (derived) rate plan.
RatePlanCode Specifies the Booking.com ID of the rate plan you want to deactivate. integer optional
RatePlanID Specifies the rate plan ID you use in your system. string optional
>>> Description Contains the rate plan name. object required
Name Specifies the name of the rate plan. string required

Request body example

The following is a request body example:

<OTA_HotelRatePlanNotifRQ>
  <RatePlans HotelCode="123456" >
    <RatePlan RatePlanNotifType="Remove" RatePlanCode="12345601" />
  </RatePlans>
</OTA_HotelRatePlanNotifRQ>

Response body example

The following is a successful response body example:

<OTA_HotelRatePlanNotifRS>
<Success />
</OTA_HotelRatePlanNotifRS>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YWVEetwbMG/FMpzy/QM5co5D+dedwfwwDyRiLnoKEGBZ3R] -->

Response body parameters

The following table describes the response elements:

Element Description Type Notes
OTA_HotelRatePlanNotifRS Contains the response data. object
> RatePlanCrossRefs Contains the RatePlanCrossRef objects. array
> warnings Contains potential warnings. These can help you improve your requests. array
> errors Contains potential errors. These can help you understand what went wrong with your request. array
> success Indicates the success of the request. object
ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.

Activating a rate plan

POST https://supply-xml.booking.com/hotels/ota/OTA_HotelRatePlanNotif

The POST /ota/OTA_HotelRatePlanNotif request enables you to reactivate a previously deactivated rate plan. To do so, you must:

  • Set RatePlanNotifType to Activate.
  • Specify the rate plan ID in RatePlanCode.

Body parameters

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

Element Attribute Description Type Required/Optional Notes
OTA_HotelRatePlanNotifRQ Contains the RatePlans array. object required
> Rateplans Contains the RatePlan objects. array required
HotelCode Specifies the unique ID of the property you create rate plans for. integer required
>> RatePlan Contains a Description object, which contains the name of the rate plan. object required
RatePlanNotifType Specifies what the exact purpose of the request is. enum required Possible values are New, Overlay, Activate, and Remove. You must set it to Activate to activate a (derived) rate plan.
RatePlanCode Specifies the Booking.com ID of the rate plan you want to activate. integer optional
RatePlanID Specifies the rate plan ID you use in your system. string optional
>>> Description Contains the rate plan name. object required
Name Specifies the name of the rate plan. string required

Request body example

The following is a request body example:

<OTA_HotelRatePlanNotifR>
  <RatePlans HotelCode="123456" >
    <RatePlan RatePlanNotifType="Activate" RatePlanCode="12345601" />
  </RatePlans>
</OTA_HotelRatePlanNotifRQ>

Response body example

The following is a successful response body example:

<OTA_HotelRatePlanNotifRS>
<Success />
</OTA_HotelRatePlanNotifRS>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YWVEetwbdwdfy/QM5co5D+dedwEGBZ3R] -->

Response body parameters

The following table describes the response elements:

Element Description Type Notes
OTA_HotelRatePlanNotifRS Contains the response data. object
> warnings Contains potential warnings. These can help you improve your requests. array
> errors Contains potential errors. These can help you understand what went wrong with your request. array
> success Indicates the success of the request. object
ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.

If you want to know more about rate relations, click here.

Creating a rate relation

POST https://supply-xml.booking.com/hotels/ota/OTA_HotelRatePlanNotif

The POST ota/OTA_HotelRatePlanNotif request also enables you to create a rate relation (or derived rate plan). This means you can create a new (child) rate plan and specify what aspects it should follow from an existing (parent) rate plan.

What is a rate relation?

You can use a rate relation (or derived rate plan) if you want to automatically base the price, restrictions, or status off another rate plan. To clarify this further see what you need to do to create a rate relation:

  • Provide the ID of the parent rate plan.
  • Indicate whether it follows the price to which the parent rate plan is connected.
  • Specify the percentage (discount or surplus) in relation to the price connected to the parent rate plan: For example, 80 refers to a 20% discount, while 120 refers to a 20% surplus.
  • Indicate whether and in what scenario it follows the status (active or deactivated) of the parent rate plan.
  • Indicate whether it follows the cancellation policy of the roomrate to which the parent rate plan is connected.
  • Indicate whether it follows the restrictions of the roomrate to which the parent rate plan is connected.

Creating or updating

To create a rate relation you set RatePlanNotifType to New. If you want to update a rate relation, you set RatePlanNotifType to Overlay and add the RatePlanCode (Booking.com ID referring to a rate plan).

Body parameters

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

Element Attribute Description Type Required/Optional Notes
OTA_HotelRatePlanNotifRQ Contains the RatePlans array. object required
> Rateplans Contains the RatePlan objects. array required
HotelCode Specifies the unique ID of the property you create rate plans for. integer required
>> RatePlan Contains a Description object, which contains the name of the rate plan. object required
RatePlanNotifType Specifies what the exact purpose of the request is. enum required Possible values are New, Overlay, Activate, and Remove.
RatePlanID Specifies the rate plan ID you use in your system. optional
>>> Description Contains the rate plan name. object required
Name Specifies the name of the rate plan. string required
>>> RateRelation Contains the details about the new rate relation. object optional
ParentRateId Specifies the ID of the parent rate plan. integer required
Percentage Specifies the percentage in relation to the price connected to the parent rate plan. integer optional Minimum value: 1. Maximum value: 200.
For example, 80 refers to a 20% discount, while 120 refers to a 20% surplus.
FollowsPrice Indicates whether the rate relation follows the price of the parent rate plan. boolean optional Possible values: 0 and 1. Default: 1.
FollowsRestrictions Indicates whether the rate relation follows the restrictions of the parent rate plan. boolean optional Possible values: 0 and 1. Default: 1.
FollowsPolicyGroup Indicates whether the rate relation follows the policies of the parent rate plan. boolean optional Possible values: 0 and 1. Default: 1.
FollowsClosed Indicates how the rate relation follows the status (active or deactivated) of the parent rate plan. enum optional Possible values:
- 0: Never follows parent rate plan status,
- 1 : Follows parent status when parent rate plan is open,
- 2 : Follows parent status when parent rate plan is closed, and
- 3 : Always follows parent rate plan status.
Default: 3.

Request body example

The following is a request body example:

<OTA_HotelRatePlanNotifRQ>
  <RatePlans HotelCode="12345">
    <RatePlan RatePlanNotifType="New">
      <Description Name="Basic rate 2 guests"/>
      <RateRelation ParentRateId="54321"
                    Percentage="90"
                    FollowsPrice="1"
                    FollowsRestrictions="1"
                    FollowsPolicyGroup="1"
                    FollowsClosed="1">
      </RateRelation>
    </RatePlan>
  </RatePlans>
</OTA_HotelRatePlanNotifRQ>

Response body example

The following is a successful response body example:

<OTA_HotelRatePlanNotifRS>
    <RatePlanCrossRefs>
        <RatePlanCrossRef RequestRatePlanCode="123490" ResponseRatePlanCode="19617133"/>
    </RatePlanCrossRefs>
    <Success />
</OTA_HotelRatePlanNotifRS>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YWVEetdwdwo5Dcz0GswDyRiLnoKEGBZ3R] -->

Response body parameters

The following table describes the response elements:

Element Attribute Description Type Notes
OTA_HotelRatePlanNotifRS Contains the response data. object
> RatePlanCrossRefs Contains the RatePlanCrossRef objects. array
>> RatePlanCrossRef Contains the mapping details in terms of your rate plan ID and Booking.com rate plan ID. object
ResponseRatePlanCode Specifies the unique Booking.com ID of the created rate relation. integer
> warnings Contains potential warnings. These can help you improve your requests. array
> errors Contains potential errors. These can help you understand what went wrong with your request. array
> success Indicates the success of the request. object
ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.

Updating a rate relation

POST https://supply-xml.booking.com/hotels/ota/OTA_HotelRatePlanNotif

The POST ota/OTA_HotelRatePlanNotif request also enables you to update a rate relation.

When updating a rate relation, it is very important to:

  • Set RatePlanNotifType to Overlay.
  • Include the RatePlanCode, which is the Booking.com ID referring to an existing rate plan.
  • Include all the other existing rate relation information and change the elements you want to update.

    → To retrieve the relevant information of an existing rate relation, see retrieving roomrates.

Body parameters

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

Element Attribute Description Type Required/Optional Notes
OTA_HotelRatePlanNotifRQ Contains the RatePlans array. object required
> Rateplans Contains the RatePlan objects. array required
HotelCode Specifies the unique ID of the property you create rate plans for. integer required
>> RatePlan Contains a Description object, which contains the name of the rate plan. object required
RatePlanNotifType Specifies what the exact purpose of the request is. enum required Possible values are New, Overlay, Activate, and Remove. You must set it to Overlay to update a rate relation.
RatePlanCode Specifies the unique ID of the rate plan you want to update. integer required
RatePlanID Specifies the rate plan ID you use in your system. string optional
>>> Description Contains the rate plan name. object required
Name Specifies the name of the rate plan. string required
>>> RateRelation Contains the details about the new rate relation. object optional -
ParentRateId Specifies the ID of the parent rate plan. integer required Default value: 1
Percentage Specifies the percentage in relation to the price connected to the parent rate plan. integer optional Minimum value: 1. Maximum value: 200.
For example, 80 refers to a 20% discount, while 120 refers to a 20% surplus.
FollowsPrice Indicates whether the rate relation follows the price of the parent rate plan. boolean optional Possible values: 0 and 1 (Follows parent rate plan). Default: 1.
FollowsRestrictions Indicates whether the rate relation follows the restrictions of the parent rate plan. boolean optional Possible values: 0 and 1 (Follows parent rate plan). Default: 1.
FollowsPolicyGroup Indicates whether the rate relation follows the policies of the parent rate plan. boolean optional Possible values: 0 and 1 (Follows parent rate plan). Default: 1.
FollowsClosed Indicates how the rate relation follows the status of the parent rate plan. integer optional Possible values:
- 0 : Never follows parent rate plan status,
- 1. : Follows parent status when parent rate plan is open,
- 2 : Follows parent status when parent rate plan is closed, and
- 3 : Always follows parent rate plan status.
Default: 3.

Request body example

The following is a request body example:

<OTA_HotelRatePlanNotifRQ>
  <RatePlans HotelCode="12345">
    <RatePlan RatePlanNotifType="Overlay" RatePlanCode="543216">
      <Description Name="Basic rate 2 guests"/>
      <RateRelation ParentRateId="54321"
                    Percentage="80"
                    FollowsPrice="1"
                    FollowsRestrictions="1"
                    FollowsPolicyGroup="1"
                    FollowsClosed="0">
      </RateRelation>
    </RatePlan>
  </RatePlans>
</OTA_HotelRatePlanNotifRQ>

Response body example

The following is a successful response body example:

<OTA_HotelRatePlanNotifRS>
  <Success />
</OTA_HotelRatePlanNotifRS>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YWVEetdwdyRiLnoKEGBZ3R] -->

Response body parameters

The following table describes the response elements:

Element Description Type Notes
OTA_HotelRatePlanNotifRS Contains the response data. object
> warnings Contains potential warnings. These can help you improve your requests. array
> errors Contains potential errors. These can help you understand what went wrong with your request. array
> success Indicates the success of the request. object
ruid Specifies the unique ID of the request. string You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.