# Managing rate plans

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

## What is a rate plan?

A *rate plan* is simply a name you use to organize prices. To add [conditions such as a cancellation policy, prepayment policy, and meal plan,](/connectivity/docs/room-type-and-rate-plan-management/understanding-room-types-and-rate-plans/#basic-definitions) you must [create a roomrate.](/connectivity/docs/room-type-and-rate-plan-management/managing-roomrates/#creating-a-roomrate)

→ To learn more about rate plans, conditions, and roomrates, [see basic definitions.](/connectivity/docs/room-type-and-rate-plan-management/understanding-room-types-and-rate-plans/#basic-definitions)

## What falls under managing rate plans?

Managing rate plans involves the following actions:

- [Creating a rate plan](#create-a-rate-plan)
- [Updating a rate plan](#update-a-rate-plan)
- [Deactivating a rate plan](#deactivate-a-rate-plan)
- [Activating a rate plan](#activate-a-rate-plan)
- [Creating rate with rate relations](#create-a-rate-relation) (derived rate plans)
- [Updating rate with rate relations](#update-a-rate-relation)
- [Retrieving rate plans](#retrieve-rate-plans) (active and deactivated)
- [Creating rate plans with customized business models](/connectivity/docs/business-models-api/managing-business-models)


## Create a rate plan

Use the `OTA_HotelRatePlanNotif` endpoint to create a rate plan for your property.

### Endpoint


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

### Request

#### Headers

| Header | Description | Type | Required | Notes |
|  --- | --- | --- | --- | --- |
| `Accept-Version` | Specify the version number to get the API functionality specific to that version. | string | Required | Supports the following values:- 1.1: Current version (default) |
| `Content-Type` | Request content type | string | Required | Must be `application/xml` |


#### Body parameters

| Element | Attribute | Description | Type | Required | 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: `New`, `Overlay`, `Activate`, `Remove`. 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


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

### Response

#### Response body example - Success


```xml
<?xml version='1.0' encoding='UTF-8'?>
<OTA_HotelRatePlanNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelRateAmountNotifRS.xsd"
                          Version="3.000">
  <RatePlanCrossRefs>
    <RatePlanCrossRef RequestRatePlanCode="123456" ResponseRatePlanCode="19617122"/>
  </RatePlanCrossRefs>
  <Success/>
</OTA_HotelRatePlanNotifRS>

<!-- RUID: [xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx] -->
```

#### Error response (HTTP 400)


```xml
<OTA_HotelRatePlanNotifRS>
    <Errors>
        <Error Code="497" ShortText="Access denied while trying to update rate" Details="hotel_ids: 15007123; rate_ids: 51727020"/>
    </Errors>
</OTA_HotelRatePlanNotifRS>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YWVEetwbMG/FMpzy/QM5cwDyRiLnoKEGBZ3Rcslghlzsoierhgvs3efsve] -->
```

Rate plan limits
- v1.1: Maximum 200 active rate plans per property


#### Response body parameters

| 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 | Only present if you specified `RatePlanID` in the request |
|  | `ResponseRatePlanCode` | Specifies the unique Booking.com ID of the created rate plan | integer |  |
| **>** `success` |  | Indicates the success of the request | object |  |
| **>** `Warnings` |  | Groups a list of individual warnings. | object | - |
| **>>** `Warning` |  | List details of individual warnings. | object | Warnings can occur even if the response contains `Success`. |
|  | `Code` | OTA EWT code. | string | See [Error code table](#error-codes). |
|  | `Details` | Contains additional context about where the warning occurred. | string | May include identifiers such as `hotel_id`, `room_id`, `rate_id`, or `date` to help identify the specific data that caused the warning. |
|  | `ShortText` | Warning message. | string | - |
| **>** `Errors` |  | Groups a list of individual errors. | object | - |
| **>>** `Error` |  | List details of individual errors. | object | - |
|  | `Code` | OTA EWT code. | string | See [Error code table](#error-codes). |
|  | `Details` | Contains additional context about where the error occurred. | string | May include identifiers such as `hotel_id`, `room_id`, `rate_id`, or `date` to help identify the specific data that caused the error. |
|  | `ShortText` | Error message. | string | - |


## Update a rate plan

Use the `OTA_HotelRatePlanNotif` endpoint to update (rename) a rate plan for your property.

### Endpoint


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

### Request

#### Headers

| Header | Description | Type | Required | Notes |
|  --- | --- | --- | --- | --- |
| `Accept-Version` | Specify the version number to get the API functionality specific to that version. | string | Required | Supports the following values:- 1.1: Current version (default) |
| `Content-Type` | Request content type | string | Required | Must be `application/xml` |


#### Body parameters

| Element | Attribute | Description | Type | Required | 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 the purpose of the request | enum | Required | Possible values: `New`, `Overlay`, `Activate`, `Remove`. Use `Overlay` to update a rate plan |
|  | `RatePlanCode` | Specifies the unique Booking.com 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 |  |


Retrieving rate plan IDs
To retrieve rate plans and their `RatePlanCode`, see [retrieving rate plans](#retrieve-rate-plans).

#### Request body example


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

### Response

#### Response body example


```xml
<?xml version='1.0' encoding='UTF-8'?>
<OTA_HotelRatePlanNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelRateAmountNotifRS.xsd"
                          Version="3.000">
  <RatePlanCrossRefs>
    <RatePlanCrossRef RequestRatePlanCode="123456" ResponseRatePlanCode="19617122"/>
  </RatePlanCrossRefs>
  <Success/>
</OTA_HotelRatePlanNotifRS>

<!-- RUID: [xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx] -->
```

#### Response body parameters

| Element | Attribute | Description | Type | Notes |
|  --- | --- | --- | --- | --- |
| `OTA_HotelRatePlanNotifRS` |  | Contains the response data | object |  |
| **>** `success` |  | Indicates the success of the request | object |  |
| **>** `Warnings` |  | Groups a list of individual warnings. | object | - |
| **>>** `Warning` |  | List details of individual warnings. | object | Warnings can occur even if the response contains `Success`. |
|  | `Code` | OTA EWT code. | string | See [Error code table](#error-codes). |
|  | `Details` | Contains additional context about where the warning occurred. | string | May include identifiers such as `hotel_id`, `room_id`, `rate_id`, or `date` to help identify the specific data that caused the warning. |
|  | `ShortText` | Warning message. | string | - |
| **>** `Errors` |  | Groups a list of individual errors. | object | - |
| **>>** `Error` |  | List details of individual errors. | object | - |
|  | `Code` | OTA EWT code. | string | See [Error code table](#error-codes). |
|  | `Details` | Contains additional context about where the error occurred. | string | May include identifiers such as `hotel_id`, `room_id`, `rate_id`, or `date` to help identify the specific data that caused the error. |
|  | `ShortText` | Error message. | string | - |


## Deactivate a rate plan

Use the `OTA_HotelRatePlanNotif` endpoint to deactivate an active rate plan.

### Endpoint


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

Deactivating causes roomrates to be deactivated
If you deactivate a rate plan, all room-rates (products) you have created for a property with this rate plan become deactivated as well. This also means any inventory is removed.

If you decide to activate a deactivated rate plan, you must both [create roomrates](/connectivity/docs/room-type-and-rate-plan-management/managing-roomrates/#creating-a-roomrate) and [push inventory (availability)](/connectivity/docs/ari) again.

### Request

#### Headers

| Header | Description | Type | Required | Notes |
|  --- | --- | --- | --- | --- |
| `Accept-Version` | Specify the version number to get the API functionality specific to that version. | string | Required | Supports the following values:- 1.1: Current version (default) |
| `Content-Type` | Request content type | string | Required | Must be `application/xml` |


#### Body parameters

| Element | Attribute | Description | Type | Required | 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 the purpose of the request | enum | Required | Possible values: `New`, `Overlay`, `Activate`, `Remove`. Use `Remove` to deactivate a rate plan |
|  | `RatePlanCode` | Specifies the Booking.com ID of the rate plan you want to deactivate | 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 |  |


#### Request body example


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

### Response

#### Response body example


```xml
<?xml version='1.0' encoding='UTF-8'?>
<OTA_HotelRatePlanNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelRateAmountNotifRS.xsd">
    <Success/>
</OTA_HotelRatePlanNotifRS>
<!-- RUID: [XXXXXXXXXXXXXXXXXXXXXXXXXXXXX] -->
```

#### Response body parameters

| Element | Attribute | Description | Type | Notes |
|  --- | --- | --- | --- | --- |
| `OTA_HotelRatePlanNotifRS` |  | Contains the response data | object |  |
| **>** `success` |  | Indicates the success of the request | object |  |
| **>** `Warnings` |  | Groups a list of individual warnings. | object | - |
| **>>** `Warning` |  | List details of individual warnings. | object | Warnings can occur even if the response contains `Success`. |
|  | `Code` | OTA EWT code. | string | See [Error code table](#error-codes). |
|  | `Details` | Contains additional context about where the warning occurred. | string | May include identifiers such as `hotel_id`, `room_id`, `rate_id`, or `date` to help identify the specific data that caused the warning. |
|  | `ShortText` | Warning message. | string | - |
| **>** `Errors` |  | Groups a list of individual errors. | object | - |
| **>>** `Error` |  | List details of individual errors. | object | - |
|  | `Code` | OTA EWT code. | string | See [Error code table](#error-codes). |
|  | `Details` | Contains additional context about where the error occurred. | string | May include identifiers such as `hotel_id`, `room_id`, `rate_id`, or `date` to help identify the specific data that caused the error. |
|  | `ShortText` | Error message. | string | - |


## Activate a rate plan

Use the `OTA_HotelRatePlanNotif` endpoint to reactivate a previously deactivated rate plan.

### Endpoint


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

### Request

#### Headers

| Header | Description | Type | Required | Notes |
|  --- | --- | --- | --- | --- |
| `Accept-Version` | Specify the version number to get the API functionality specific to that version. | string | Required | Supports the following values:- 1.1: Current version (default) |
| `Content-Type` | Request content type | string | Required | Must be `application/xml` |


#### Body parameters

| Element | Attribute | Description | Type | Required | 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: `New`, `Overlay`, `Activate`, `Remove`. Use `Activate` to activate a rate plan |
|  | `RatePlanCode` | Specifies the Booking.com ID of the rate plan you want to activate | 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 |  |


#### Request body example


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

### Response

#### Response body example


```xml
<?xml version='1.0' encoding='UTF-8'?>
<OTA_HotelRatePlanNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelRateAmountNotifRS.xsd">
    <Success/>
</OTA_HotelRatePlanNotifRS>
        <!-- RUID: [XXXXXXXXXXXXXXXXXXXXXXXXXXXXX] -->
```

#### Response body parameters

| Element | Attribute | Description | Type | Notes |
|  --- | --- | --- | --- | --- |
| `OTA_HotelRatePlanNotifRS` |  | Contains the response data | object |  |
| **>** `success` |  | Indicates the success of the request | object |  |
| **>** `Warnings` |  | Groups a list of individual warnings. | object | - |
| **>>** `Warning` |  | List details of individual warnings. | object | Warnings can occur even if the response contains `Success`. |
|  | `Code` | OTA EWT code. | string | See [Error code table](#error-codes). |
|  | `Details` | Contains additional context about where the warning occurred. | string | May include identifiers such as `hotel_id`, `room_id`, `rate_id`, or `date` to help identify the specific data that caused the warning. |
|  | `ShortText` | Warning message. | string | - |
| **>** `Errors` |  | Groups a list of individual errors. | object | - |
| **>>** `Error` |  | List details of individual errors. | object | - |
|  | `Code` | OTA EWT code. | string | See [Error code table](#error-codes). |
|  | `Details` | Contains additional context about where the error occurred. | string | May include identifiers such as `hotel_id`, `room_id`, `rate_id`, or `date` to help identify the specific data that caused the error. |
|  | `ShortText` | Error message. | string | - |


## Create a rate relation

Use the `OTA_HotelRatePlanNotif` endpoint to create a rate relation (or derived rate plan). This allows you to 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 of another rate plan. 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


### Endpoint


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

### Request

#### Headers

| Header | Description | Type | Required | Notes |
|  --- | --- | --- | --- | --- |
| `Accept-Version` | Specify the version number to get the API functionality specific to that version. | string | Required | Supports the following values:- 1.1: Current version (default) |
| `Content-Type` | Request content type | string | Required | Must be `application/xml` |


#### Body parameters

| Element | Attribute | Description | Type | Required | 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: `New`, `Overlay`, `Activate`, `Remove`. Use `New` to create a rate relation |
|  | `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 Booking.com ID of the parent rate plan | integer | Required |  |
|  | `Percentage` | Specifies the percentage in relation to the price connected to the parent rate plan | float | Optional | Minimum: `1`. Maximum: `200`. For example, `80` = 20% discount, `120` = 20% surplus |
|  | `Amount` | Specifies a fixed amount to add to (or subtract from) the parent rate plan price | float | Optional | Can be a positive or negative number |
|  | `FollowsPrice` | Indicates whether the rate relation follows the price of the parent rate plan | boolean | Optional | Possible values: `0`, `1`. Default: `1` |
|  | `FollowsRestrictions` | Indicates whether the rate relation follows the restrictions of the parent rate plan | boolean | Optional | Possible values: `0`, `1`. Default: `1` |
|  | `FollowsPolicyGroup` | Indicates whether the rate relation follows the policies of the parent rate plan | boolean | Optional | Possible values: `0`, `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 - `3`: Always follows parent rate plan status Default: `3` |


#### Request body example


```xml
<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

#### Response body example


```xml
<?xml version='1.0' encoding='UTF-8'?>
<OTA_HotelRatePlanNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelRateAmountNotifRS.xsd"
                          Version="3.000">
   <RatePlanCrossRefs>
      <RatePlanCrossRef RequestRatePlanCode="123490" ResponseRatePlanCode="19617133"/>
   </RatePlanCrossRefs>
   <Success/>
</OTA_HotelRatePlanNotifRS>

<!-- RUID: [xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx] -->
```

#### Response body parameters

| 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 | Only present if you specified `RatePlanID` in the request |
|  | `ResponseRatePlanCode` | Specifies the unique Booking.com ID of the created rate plan | integer |  |
| **>** `success` |  | Indicates the success of the request | object |  |
| **>** `Warnings` |  | Groups a list of individual warnings. | object | - |
| **>>** `Warning` |  | List details of individual warnings. | object | Warnings can occur even if the response contains `Success`. |
|  | `Code` | OTA EWT code. | string | See [Error code table](#error-codes). |
|  | `Details` | Contains additional context about where the warning occurred. | string | May include identifiers such as `hotel_id`, `room_id`, `rate_id`, or `date` to help identify the specific data that caused the warning. |
|  | `ShortText` | Warning message. | string | - |
| **>** `Errors` |  | Groups a list of individual errors. | object | - |
| **>>** `Error` |  | List details of individual errors. | object | - |
|  | `Code` | OTA EWT code. | string | See [Error code table](#error-codes). |
|  | `Details` | Contains additional context about where the error occurred. | string | May include identifiers such as `hotel_id`, `room_id`, `rate_id`, or `date` to help identify the specific data that caused the error. |
|  | `ShortText` | Error message. | string | - |


## Update a rate relation

Use the `OTA_HotelRatePlanNotif` endpoint to update an existing rate relation.

Include all existing information
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 only the elements you want to update
- To remove the rate relation while keeping the rate plan, Provide an empty `RateRelation` object


→ To retrieve the relevant information of an existing rate relation, see [retrieving roomrates.](/connectivity/docs/room-type-and-rate-plan-management/managing-roomrates/#retrieving-active-roomrates)

### Endpoint


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

### Request

#### Headers

| Header | Description | Type | Required | Notes |
|  --- | --- | --- | --- | --- |
| `Accept-Version` | Specify the version number to get the API functionality specific to that version. | string | Required | Supports the following values:- 1.1: Current version (default) |
| `Content-Type` | Request content type | string | Required | Must be `application/xml` |


#### Body parameters

| Element | Attribute | Description | Type | Required | 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: `New`, `Overlay`, `Activate`, `Remove`. Use `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 rate relation | object | Optional |  |
|  | `ParentRateId` | Specifies the ID of the parent rate plan | integer | Required | Default: `1` |
|  | `Percentage` | Specifies the percentage in relation to the price connected to the parent rate plan | integer | Optional | Minimum: `1`. Maximum: `200`. For example, `80` = 20% discount, `120` = 20% surplus |
|  | `FollowsPrice` | Indicates whether the rate relation follows the price of the parent rate plan | boolean | Optional | Possible values: `0`, `1` (Follows parent). Default: `1` |
|  | `FollowsRestrictions` | Indicates whether the rate relation follows the restrictions of the parent rate plan | boolean | Optional | Possible values: `0`, `1` (Follows parent). Default: `1` |
|  | `FollowsPolicyGroup` | Indicates whether the rate relation follows the policies of the parent rate plan | boolean | Optional | Possible values: `0`, `1` (Follows parent). 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 - `3`: Always follows parent rate plan status Default: `3` |


#### Request body example


```xml
<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

#### Response body example


```xml
<?xml version='1.0' encoding='UTF-8'?>
<OTA_HotelRatePlanNotifRS xmlns="http://www.opentravel.org/OTA/2003/05"
                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                          xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelRateAmountNotifRS.xsd">
    <Success/>
</OTA_HotelRatePlanNotifRS>
<!-- RUID: [XXXXXXXXXXXXXXXXXXXXXXXXXXXXX] -->
```

#### Response body parameters

| 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 | Only present if you specified `RatePlanID` in the request |
|  | `ResponseRatePlanCode` | Specifies the unique Booking.com ID of the created rate plan | integer |  |
| **>** `success` |  | Indicates the success of the request | object |  |
| **>** `Warnings` |  | Groups a list of individual warnings. | object | - |
| **>>** `Warning` |  | List details of individual warnings. | object | Warnings can occur even if the response contains `Success`. |
|  | `Code` | OTA EWT code. | string | See [Error code table](#error-codes). |
|  | `Details` | Contains additional context about where the warning occurred. | string | May include identifiers such as `hotel_id`, `room_id`, `rate_id`, or `date` to help identify the specific data that caused the warning. |
|  | `ShortText` | Warning message. | string | - |
| **>** `Errors` |  | Groups a list of individual errors. | object | - |
| **>>** `Error` |  | List details of individual errors. | object | - |
|  | `Code` | OTA EWT code. | string | See [Error code table](#error-codes). |
|  | `Details` | Contains additional context about where the error occurred. | string | May include identifiers such as `hotel_id`, `room_id`, `rate_id`, or `date` to help identify the specific data that caused the error. |
|  | `ShortText` | Error message. | string | - |


## Retrieve rate plans

Use the `POST /xml/rates` endpoint to retrieve rate plans of a property.

### Endpoint


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

### Request

#### Headers

| Header | Description | Type | Required | Notes |
|  --- | --- | --- | --- | --- |
| `Accept-Version` | Specify the version number to get the API functionality specific to that version. | string | Required | Supports the following values:- 1.1: Current version (default) |
| `Content-Type` | Request content type | string | Required | Must be `application/xml` |


#### Body parameters

| Element | Description | Type | Required | 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: - `1`: All rate plans with active attribute - `3`: All active rate plans with active attribute set to active - `6`: All deactivated rate plans with active attribute set to deactivated |


#### Request body example


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

### Response

#### Response body example


```xml
<?xml version='1.0' encoding='UTF-8'?>
<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: [XXXXXXXXXXXXXXXXXXXXXXXXXXX] -->
```

#### Response body parameters

| 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: `1` (active), `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 | string |  |
|  | `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), `0` (Not a child rate plan) |


## Error codes

The following table lists the possible error codes you may encounter when managing rate plans:

| Error Code | Error Message | Description | Resolution |
|  --- | --- | --- | --- |
| `321` | `OTA_HotelRatePlanNotifRQ: missing RatePlans element` | The request is missing the required `RatePlans` element | Ensure your request includes the `RatePlans` element in the request body |
| `321` | `RatePlans: missing RatePlan element(s)` | The `RatePlans` element doesn't contain any `RatePlan` elements | Add at least one `RatePlan` element within the `RatePlans` array |
| `321` | `RatePlanCode is mandatory when RatePlanNotifType is not set to 'New'` | The `RatePlanCode` is missing when updating, activating, or deactivating a rate plan | Include the `RatePlanCode` attribute when `RatePlanNotifType` is set to `Overlay`, `Activate`, or `Remove` |
| `497` | `Access denied while trying to update rate` | You don't have permission to update the specified rate plan | Verify your authentication credentials and ensure you have the necessary permissions for this property |
| `562` | `Limit 200 of number of Rates has reached` | The property has reached the maximum limit of 200 active rate plans (v1.1) | Deactivate unused rate plans before creating new ones. |
| `592` | `Rate with the same name already exists` | A rate plan with the specified name already exists for this property | Use a different name for the rate plan or update the existing rate plan instead |
| `592` | `Rate name invalid` | The provided rate plan name doesn't meet the validation requirements | Ensure the rate plan name meets the required format and length constraints |
| `592` | `Rate business model invalid` | The specified business model for the rate plan is not valid | Verify the business model configuration. For more information, see [Managing business models](/connectivity/docs/business-models-api/managing-business-models) |
| `592` | `Cannot modify rate business model` | You cannot change the business model of an existing rate plan | The business model cannot be modified after creation. Create a new rate plan with the desired business model instead |
| `592` | `Cannot assign rate business model %s to rate plan %s having rate relations` | You cannot assign a business model to a rate plan that has rate relations (derived rate plans) | Remove the rate relations before assigning a business model, or assign the business model to the parent rate plan |
| `733` | `RatePlanNotifType cannot be 'New' when RatePlanCode provided` | You're trying to create a new rate plan but provided an existing `RatePlanCode` | Remove the `RatePlanCode` attribute when creating a new rate plan, or set `RatePlanNotifType` to `Overlay` to update an existing rate plan |