Last updated

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:

ElementAttributeDescriptionTypeRequired/OptionalNotes
OTA_HotelRatePlanNotifRQContains the RatePlans array.objectrequired
> RateplansContains the RatePlan objects.arrayrequired
HotelCodeSpecifies the unique ID of the property you create rate plans for.integerrequired
>> RatePlanContains a Description object, which contains the name of the rate plan.objectrequired
RatePlanNotifTypeSpecifies the purpose of the request.enumrequiredPossible values are New, Overlay, Activate, and Remove. You must use New to create a rate plan.
RatePlanIDSpecifies the rate plan ID you use in your system.stringoptional
>>> DescriptionContains the rate plan name.objectrequired
NameSpecifies the name of the rate plan.stringrequired

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:

ElementAttributeDescriptionTypeNotes
OTA_HotelRatePlanNotifRSContains the response data.object
> RatePlanCrossRefsContains the RatePlanCrossRef objects.array
>> RatePlanCrossRefContains the mapping details in terms of your rate plan ID and Booking.com rate plan ID.object
RequestRatePlanCodeSpecifies your rate plan ID.stringTo see this, you must have specified the RatePlanID attribute in the RatePlan object of your request.
ResponseRatePlanCodeSpecifies the unique Booking.com ID of the created rate plan.integer
> warningsContains potential warnings. These can help you improve your requests.array
> errorsContains potential errors. These can help you understand what went wrong with your request.array
> successIndicates the success of the request.object
ruidSpecifies the unique ID of the request.stringYou 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:

ElementAttributeDescriptionTypeRequired/OptionalNotes
OTA_HotelRatePlanNotifRQContains the RatePlans array.objectrequired
> RateplansContains the RatePlan objects.arrayrequired
HotelCodeSpecifies the unique ID of the property you update rate plans for.integerrequired
>> RatePlanContains a Description object, which contains the name of the rate plan.objectrequired
RatePlanNotifTypeSpecifies what the exact purpose of the request is.enumrequiredPossible values are New, Overlay, Activate, and Remove. You must set it to Overlay when updating a rate plan.
RatePlanIDSpecifies the rate plan ID you use in your system.stringoptional
RatePlanCodeSpecifies the unique ID of the rate plan you want to update.integerrequired
>>> DescriptionContains the rate plan name.objectrequired
NameSpecifies the name of the rate plan.stringrequired

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:

ElementDescriptionTypeNotes
OTA_HotelRatePlanNotifRSContains the response data.object
> warningsContains potential warnings. These can help you improve your requests.array
> errorsContains potential errors. These can help you understand what went wrong with your request.array
> successIndicates the success of the request.object
ruidSpecifies the unique ID of the request.stringYou 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:

ElementDescriptionTypeRequired/OptionalNotes
requestContains the request information.objectrequired
> hotel_idSpecifies the unique ID of the property you want to retrieve the rate plans for.integerrequired
> show_rates_statusSpecifies the code for the status of the rate plans you want to retrieve.integeroptionalPossible 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:

ElementAttributeDescriptionTypeNotes
ratesContains the rate objects.object
> rateContains the rate plan information.object
idSpecifies the unique Booking.com ID of the rate plan.integer
activeIndicates whether the rate plan is active or deactivatedbooleanPossible values are: 1 (active) and 0 (deactivated)
hotel_idSpecifies the unique ID of the property you retrieved the rate plans for.integer
hotel_nameSpecifies the name of the property you retrieved the rate plans for.integer
is_child_rateSpecifies whether the rate plan has a rate relation with a parent rate plan.booleanPossible value: 1 (Yes, rate plan is a child rate plan)
ruidSpecifies the unique ID of the request.stringYou 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:

ElementAttributeDescriptionTypeRequired/OptionalNotes
OTA_HotelRatePlanNotifRQContains the RatePlans array.objectrequired
> RateplansContains the RatePlan objects.arrayrequired
HotelCodeSpecifies the unique ID of the property.integerrequired
>> RatePlanContains a Description object, which contains the name of the rate plan.objectrequired
RatePlanNotifTypeSpecifies what the exact purpose of the request is.enumrequiredPossible values are New, Overlay, Activate, and Remove. You must set it to Remove to deactivate a (derived) rate plan.
RatePlanCodeSpecifies the Booking.com ID of the rate plan you want to deactivate.integeroptional
RatePlanIDSpecifies the rate plan ID you use in your system.stringoptional
>>> DescriptionContains the rate plan name.objectrequired
NameSpecifies the name of the rate plan.stringrequired

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:

ElementDescriptionTypeNotes
OTA_HotelRatePlanNotifRSContains the response data.object
> RatePlanCrossRefsContains the RatePlanCrossRef objects.array
> warningsContains potential warnings. These can help you improve your requests.array
> errorsContains potential errors. These can help you understand what went wrong with your request.array
> successIndicates the success of the request.object
ruidSpecifies the unique ID of the request.stringYou 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:

ElementAttributeDescriptionTypeRequired/OptionalNotes
OTA_HotelRatePlanNotifRQContains the RatePlans array.objectrequired
> RateplansContains the RatePlan objects.arrayrequired
HotelCodeSpecifies the unique ID of the property you create rate plans for.integerrequired
>> RatePlanContains a Description object, which contains the name of the rate plan.objectrequired
RatePlanNotifTypeSpecifies what the exact purpose of the request is.enumrequiredPossible values are New, Overlay, Activate, and Remove. You must set it to Activate to activate a (derived) rate plan.
RatePlanCodeSpecifies the Booking.com ID of the rate plan you want to activate.integeroptional
RatePlanIDSpecifies the rate plan ID you use in your system.stringoptional
>>> DescriptionContains the rate plan name.objectrequired
NameSpecifies the name of the rate plan.stringrequired

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:

ElementDescriptionTypeNotes
OTA_HotelRatePlanNotifRSContains the response data.object
> warningsContains potential warnings. These can help you improve your requests.array
> errorsContains potential errors. These can help you understand what went wrong with your request.array
> successIndicates the success of the request.object
ruidSpecifies the unique ID of the request.stringYou 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:

ElementAttributeDescriptionTypeRequired/OptionalNotes
OTA_HotelRatePlanNotifRQContains the RatePlans array.objectrequired
> RateplansContains the RatePlan objects.arrayrequired
HotelCodeSpecifies the unique ID of the property you create rate plans for.integerrequired
>> RatePlanContains a Description object, which contains the name of the rate plan.objectrequired
RatePlanNotifTypeSpecifies what the exact purpose of the request is.enumrequiredPossible values are New, Overlay, Activate, and Remove.
RatePlanIDSpecifies the rate plan ID you use in your system.optional
>>> DescriptionContains the rate plan name.objectrequired
NameSpecifies the name of the rate plan.stringrequired
>>> RateRelationContains the details about the new rate relation.objectoptional
ParentRateIdSpecifies the ID of the parent rate plan.integerrequired
PercentageSpecifies the percentage in relation to the price connected to the parent rate plan.integeroptionalMinimum value: 1. Maximum value: 200.
For example, 80 refers to a 20% discount, while 120 refers to a 20% surplus.
FollowsPriceIndicates whether the rate relation follows the price of the parent rate plan.booleanoptionalPossible values: 0 and 1. Default: 1.
FollowsRestrictionsIndicates whether the rate relation follows the restrictions of the parent rate plan.booleanoptionalPossible values: 0 and 1. Default: 1.
FollowsPolicyGroupIndicates whether the rate relation follows the policies of the parent rate plan.booleanoptionalPossible values: 0 and 1. Default: 1.
FollowsClosedIndicates how the rate relation follows the status (active or deactivated) of the parent rate plan.enumoptionalPossible 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:

ElementAttributeDescriptionTypeNotes
OTA_HotelRatePlanNotifRSContains the response data.object
> RatePlanCrossRefsContains the RatePlanCrossRef objects.array
>> RatePlanCrossRefContains the mapping details in terms of your rate plan ID and Booking.com rate plan ID.object
ResponseRatePlanCodeSpecifies the unique Booking.com ID of the created rate relation.integer
> warningsContains potential warnings. These can help you improve your requests.array
> errorsContains potential errors. These can help you understand what went wrong with your request.array
> successIndicates the success of the request.object
ruidSpecifies the unique ID of the request.stringYou 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:

ElementAttributeDescriptionTypeRequired/OptionalNotes
OTA_HotelRatePlanNotifRQContains the RatePlans array.objectrequired
> RateplansContains the RatePlan objects.arrayrequired
HotelCodeSpecifies the unique ID of the property you create rate plans for.integerrequired
>> RatePlanContains a Description object, which contains the name of the rate plan.objectrequired
RatePlanNotifTypeSpecifies what the exact purpose of the request is.enumrequiredPossible values are New, Overlay, Activate, and Remove. You must set it to Overlay to update a rate relation.
RatePlanCodeSpecifies the unique ID of the rate plan you want to update.integerrequired
RatePlanIDSpecifies the rate plan ID you use in your system.stringoptional
>>> DescriptionContains the rate plan name.objectrequired
NameSpecifies the name of the rate plan.stringrequired
>>> RateRelationContains the details about the new rate relation.objectoptional-
ParentRateIdSpecifies the ID of the parent rate plan.integerrequiredDefault value: 1
PercentageSpecifies the percentage in relation to the price connected to the parent rate plan.integeroptionalMinimum value: 1. Maximum value: 200.
For example, 80 refers to a 20% discount, while 120 refers to a 20% surplus.
FollowsPriceIndicates whether the rate relation follows the price of the parent rate plan.booleanoptionalPossible values: 0 and 1 (Follows parent rate plan). Default: 1.
FollowsRestrictionsIndicates whether the rate relation follows the restrictions of the parent rate plan.booleanoptionalPossible values: 0 and 1 (Follows parent rate plan). Default: 1.
FollowsPolicyGroupIndicates whether the rate relation follows the policies of the parent rate plan.booleanoptionalPossible values: 0 and 1 (Follows parent rate plan). Default: 1.
FollowsClosedIndicates how the rate relation follows the status of the parent rate plan.integeroptionalPossible 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:

ElementDescriptionTypeNotes
OTA_HotelRatePlanNotifRSContains the response data.object
> warningsContains potential warnings. These can help you improve your requests.array
> errorsContains potential errors. These can help you understand what went wrong with your request.array
> successIndicates the success of the request.object
ruidSpecifies the unique ID of the request.stringYou can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong.