# Retrieving promotion details

Use `getpromotions` endpoint to retrieve promotions by:

- ID,
- Promotion name, and/or,
- Active status.


The endpoint returns the details of the most recent update for promotions with multiple updates.
The response includes statistics like total revenue, number of nights reserved, total bookings, and total cancellations.

Promotion statistics available for the last 12 months
Booking.com will start retaining promotion statistics for 12 months, effective on September 15, 2024. The `getpromotions` endpoint will thereby return promotion statistics up to 12 months.

For more information on how to create and manage promotions, see [Managing promotions.](/connectivity/docs/b_xml-promotions)

This topic also provides the [UI/UX recommendations](#uiux-recommendations) for the `getpromotions` endpoint.

## URL


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

## Sample request

You can use the `id` value of the existing promotion in the `id` request parameter.


```xml
<request>
    <hotel_id>1234</hotel_id>
    <id>TB1596220037234</id>
    <active>1</active>
    <name>Summer Deal</name>
</request>
```

## Request body

| Field | Description | Type | Occurrences | Notes |
|  --- | --- | --- | --- | --- |
| `request` | Root element. | object | 1..1 | - |
| `hotel_id` | The ID of the property you want to retrive promotions for. | integer | 1..1 | - |
| `id` | (optional) An ID for the specific promotion. | string | 0..1 | - |
| `active` | (optional) The promotion's status (active/deactivated). | boolean | 0..1 | Accepts: `1` (active), `0` (deactivated). |
| `name` | (optional) The promotion's name. | string | 0..1 | - |


## Sample response

This example contains all possible fields that can be included in the response.


```xml
<promotions>
    <promotion id="TB12345596220037" name="Summer Deal" type="basic" target_channel="public" min_stay_through="2" non_refundable="0" min_booked_nights="2" no_cc_promotion="0" active="1">
    <last_minute unit="-1" value="-1"></last_minute>
    <early_booker value="-1"></early_booker>
    <book_date start="-1" end="-1"></book_date>
    <book_time start="-1" end="-1"></book_time>
    <stay_date start="2024-08-20" end="2024-08-30">
      <active_weekdays>
        <active_weekday>Mon</active_weekday>
        <active_weekday>Tue</active_weekday>
        <active_weekday>wed</active_weekday>
        <active_weekday>Thu</active_weekday>
        <active_weekday>Fri</active_weekday>
        <active_weekday>Sat</active_weekday>
        <active_weekday>Sun</active_weekday>
      </active_weekdays>
      <excluded_dates>
        <excluded_date>2024-08-22</excluded_date>
      </excluded_dates>
    </stay_date>
    <additional_dates>
      <additional_date>2023-09-01</additional_date>
      <additional_date>2023-08-31</additional_date>
    </additional_dates>
    <rooms>
      <room id="12223"></room>
      <room id="12345"></room>
    </rooms>
    <parent_rates>
      <parent_rate id="435345"></parent_rate>
    </parent_rates>
    <discount value="5"></discount>
  </promotion>
  <promotion id="TB34234596220037" name="Lastminute hurry" type="last_minute" target_channel="public" min_stay_through="0" non_refundable="1" min_booked_nights="0" no_cc_promotion="0" active="1">
    <last_minute unit="hour" value="8"></last_minute>
    <early_booker value="-1"></early_booker>
    <book_date start="-1" end="-1"></book_date>
    <book_time start="-1" end="-1"></book_time>
    <stay_date start="2023-06-10" end="2023-06-10">
      <active_weekdays>
        <active_weekday>Fri</active_weekday>
      </active_weekdays>
      <excluded_dates></excluded_dates>
    </stay_date>
    <additional_dates></additional_dates>
    <rooms>
      <room id="1000419"></room>
    </rooms>
    <parent_rates>
      <parent_rate id="12345"></parent_rate>
      <parent_rate id="47568"></parent_rate>
    </parent_rates>
    <discount value="10"></discount>
    <stats>
      <total_revenue value="418.95" currency="EUR"></total_revenue>
      <nr_room_nights>1</nr_room_nights>
      <nr_bookings>1</nr_bookings>
      <nr_cancellations>0</nr_cancellations>
    </stats>
  </promotion>
</promotions>
<!-- RUID: [...] -->
```

## Response body parameters

This table provides some extra detail about some of the fields in the response.

Note
Not all fields are relevant for all response types. A
value of `-1` indicates that the current field is not relevant for the
current response type.

| Element | Attribute | Description | Type | Notes |
|  --- | --- | --- | --- | --- |
| `promotions` |  | Root element. | array of `promotion` |  |
| **>** `promotion` |  | Promotion details. | object |  |
|  | `id` | The most recently generated promotion ID. | string |  |
|  | `name` | Name of the promotion. | string |  |
| **>>** `stats` |  | Includes statistical details | object |  |
|  | `non_refundable` | Whether or not the guest can receive a refund if they cancel. | boolean |  |
|  | `total_revenue` | The gross revenue from all bookings with this promotion, in the property's default currency. | integer |  |
|  | `nr_room_nights` | The total number of room nights booked with this promotion. | integer |  |
|  | `nr_bookings` | The total number of gross bookings with this promotion. | integer |  |
|  | `nr_cancellations` | The total number of cancellations with this promotion. | integer |  |


## UI/UX recommendations

We recommend displaying all of a property’s promotions in a single table with expandable rows for each promotion. As properties can often have a large number of promotions we also recommend adding some basic filters such as promotion status and type, as well as sorting for the table columns. Below we have provided an example implementation:

![Retrieving promotions details: example 1](/assets/retrieving_promotion_details_1.c1bd129b5b7cc2fd54b060f28a8538ae62fe70275a82e4f647cdf8f46f7a06c0.5cba86b9.png)

When expanding one of the promotion rows each promotion may have different information available. We recommend providing all relevant available information in this expanded view while still keeping the order of elements as consistent as possible.

![Retrieving promotions details: example 2](/assets/retrieving_promotion_details_2.3433bb1f482787a67e7fce7ec14c0d9206535a8f472d98cbbd3739e892a08cd7.5cba86b9.png)

Remember that not all promotion types can be edited and may require different CTAs in the detailed view.

## Errors

For a complete list of error codes and possible solutions, see [Troubleshooting and list of error codes](/connectivity/docs/promotions-troubleshooting).