reporting (B.XML)

Use the Reporting API to report the following types of changes to a reservation:

Read on for details about each reporting function. To learn more about the commercial and design aspects of the Reporting API, try these additional materials:

URL

Use this method and URL to call the Reporting API:

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

Report invalid credit card

Properties can mark credit cards as invalid if the card doesn't meet validation conditions (card expired, incorrect number, insufficient funds, etc.).

An invalid credit card can be reported immediately after the reservation is made, up until midnight (00:00) on the day of check-in, in the property's local timezone.

Example request: cc_is_invalid

Field details

See Request body for detailed information about each field.

<request>
  <reservation_id>123456789</reservation_id>
  <report>cc_is_invalid</report>
</request>

After a credit card is reported as invalid, the booker receives an email and SMS from Booking.com inviting them to enter different, valid credit card details before a deadline. The deadline depends on when the reservation was made, relative to the planned check-in day and time. Read more about this in our Partner Help.

If the booker does not enter valid credit card details before the deadline, the property may cancel the reservation. See Report cancellation due to invalid credit card.

Example responses: cc_is_invalid

Success

<status>enqueued</status>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY==] -->

Error 400: Credit card not required for reservation

<?xml version='1.0' standalone='yes'?>
<reporting>
    <fault code="400">
        <string>"You cannot mark credit card as invalid since it is not required"</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY] -->

Error 400: Credit card is already marked as invalid

<?xml version='1.0' standalone='yes'?>
<reporting>
    <fault code="400">
        <string>"Card is already marked as invalid"</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY] -->

Error 400: Reservation still being processed

We recommend waiting at least 1 minute after receiving a reservation before reporting an invalid credit card.

<?xml version='1.0' standalone='yes'?>
<reporting>
    <fault code="400">
        <string>"You cannot mark credit card as invalid. Please try again later"</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY] -->

Report cancellation due to invalid credit card

A property may cancel a reservation if the guest's credit card details are invalid and certain conditions are met. Read more about these conditions in our Partner Help.

Example request: cancel_reservation_invalid_cc

Field details

See Request body for detailed information about each field.

<request>
   <reservation_id>123456789</reservation_id>
   <report>cancel_reservation_invalid_cc</report>
</request>

Example responses: cancel_reservation_invalid_cc

Success

<status>ok</status>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY==] -->

Error 400: Reservation can't be cancelled

<?xml version='1.0' standalone='yes'?>
<reporting>
    <fault code="400">
        <string>"Cannot cancel the reservation. Make sure all preconditions are met"</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY==] -->

Report stay changed

A property can change the check-out date of a room and set a new price for the reservation. The booker automatically receives a confirmation email with the new reservation dates and/or price.

Room availability is not automatically updated

A changed stay can result in a room becoming available on dates it was previously booked. We do not automatically update the room's availability if this happens. The property must update their calendar in Extranet, or the Connectivity Partner must push new availability with the API.

A stay can be changed if:

  • the guest has already checked in;
  • the status of the reservation allows modifications;
  • the reservation is not overbooked;
  • the property is not a direct payment property;
  • the change does not involve setting a new check-out date for a stay whose check-out date was already changed in the last 24-hour period (calculated as 00:00–23:59 CE(S)T).

The new stay must meet these conditions:

  • the stay length is at least 1 night;
  • if the reservation is non-refundable, the new price must not be lower than the original price;
  • the new price must be at least {calculated price} * 0.1.

Example request: stay_change

Field details

See Request body for detailed information about each field.

<request>
   <reservation_id>123456789</reservation_id>
   <stay_change>
      <roomreservation_id>2345678</roomreservation_id>
      <checkin>2017-01-02</checkin>
      <checkout>2017-01-05</checkout>
      <price>1000</price>
   </stay_change>
   <stay_change>
      <roomreservation_id>3456789</roomreservation_id>
      <checkin>2017-01-03</checkin>
      <checkout>2017-01-06</checkout>
      <price>900</price>
   </stay_change>
</request>

Example responses: stay_change

Success

<status>enqueued</status>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY==] -->

Error 404: Room reservation not found

<?xml version='1.0' standalone='yes'?>
<reporting>
    <fault code="400">
        <string>"Not found error: room reservation could not be found."</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY] -->

Error 400: Room reservation doesn't belong to this property

<?xml version='1.0' standalone='yes'?>
<reporting>
    <fault code="400">
        <string>"Room reservation not within right hotel reservation."</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY] -->

Error 400: Direct payment property

<?xml version='1.0' standalone='yes'?>
<reporting>
    <fault code="400">
        <string>"Not able to change stay for a direct payment hotel."</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY] -->

Report guest no-show

If a guest doesn't show up on the planned check-in date, the property may mark the reservation (or a specific room in a multi-room reservation) as "no show". This results in either a cancellation or a modification, depending on if it is a complete or partial no-show.

The property can waive no-show fees, if desired. This means Booking.com will not charge commission for the reservation.

You can mark a reservation as a no-show from 00:00 (midnight, in property's local time) on the planned check-in date, up to 48 hours later, provided that:

  • the status of the reservation allows modifications;
  • the reservation isn't overbooked.

Note

After you mark a reservation as a no-show, it is no longer modifiable. The API returns an error if you try to change the reservation again.

A room reservation won't be considered a part of the reservation anymore if the reservation is marked as a no-show.

The property reserves the right to charge no-show fees (unless waived), in line with their cancellation policies listed on Booking.com.

The booker will receive an email explaining that (part of) their reservation has been cancelled. If the property did not waive the cancellation fees, the email will also instruct the booker to pay any cancellation costs outlined on Booking.com.

Room availability is not automatically updated

A no-show can result in a room becoming available on dates it was previously booked. We do not automatically update the room's availability if this happens. The property must update their calendar in Extranet, or the Connectivity Partner must push new availability with the API.

Example request: is_no_show

Field details

See Request body for detailed information about each field.

This request reports the full reservation as a no-show.

<request>
   <reservation_id>1234567</reservation_id>
   <report waived_fees="yes">is_no_show</report>
</request>

This request reports one room in the reservation as a no-show.

<request>
   <reservation_id>1234567</reservation_id>
   <report>
      <is_no_show roomreservation_id="2345678" waived_fees="yes" />
   </report>
</request>

Example responses: is_no_show

Success

<status>enqueued</status>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY==] -->

Error 400: Too early to cancel

<?xml version='1.0' standalone='yes'?>
<reporting>
    <fault code="400">
        <string>"Not able to cancel booking earlier than 1 day after the check in."</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY] -->

Error 400: Too late to cancel

<?xml version='1.0' standalone='yes'?>
<reporting>
    <fault code="400">
        <string>"Not able to cancel booking later than 2 days after the check in."</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY] -->

Error 400: Can't cancel, overbooked

<?xml version='1.0' standalone='yes'?>
<reporting>
    <fault code="400">
        <string>"Not able to cancel overbooked."</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY] -->

Error 400: Can't cancel, unmodifiable booking

<?xml version='1.0' standalone='yes'?>
<reporting>
    <fault code="400">
        <string>"Not able to cancel unmodifiable booking."</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY] -->

Sample Errors

Error 404: Reservation not found

These are general error messages that the API can return for any of the above requests.

<?xml version='1.0' standalone='yes'?>
<reporting>
    <fault code="404">
        <string>"Reservation 1234567 not found."</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY==] -->

Error 400: Bad request

<?xml version='1.0' standalone='yes'?>
<reporting>
    <fault code="400">
        <string>"Either a report or a stay change is required."</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY==] -->

Error 500: Generic error

<?xml version='1.0' standalone='yes'?>
<reporting>
    <fault code="500">
        <string>"Internal server error."</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY==] -->

Report guest misconduct

If a guest did damage to the property or performed any other misconduct - you can perform a report.

This type of report can only be done after reservation check-in date and no later than 7 days after check-out date.

In order to report a guest misconduct you need to:

  1. Retrieve all the possible guest misconduct categories and subcategories via Misconduct Categories Call.
    • Keep in mind that for some of report types might require to provide additional fields. You can find their descriptions in the additional_fields section of resulting xml, if there is any.
  2. Send a request with corresponding category/subcategory and additional fields.

All of the details must be provided within misconduct_details object (see an example below).

misconduct_details structure

all the fields are mandatory, unless otherwise specified

Field Description Type Possible values Notes
category_id Guest misconduct category id string - You can retrieve all possible categories and subcategories with Misconduct Categories Call.
subcategory_id Guest misconduct subcategory id string - This parameter needs to be omitted if chosen category doesn't have any subcategories
details_text Free text for any details that you want to provide string - The maximum possible length is 240 characters, it is an optional parameter
escalate_report A flag that indicates whether you would like Booking.com to follow up on this incident integer 0, 1 0 = do not escalate the report, 1 = escalate the report
rebooking_allowed A flag that indicates whether you want to prevent this guest from booking your properties in future integer 0, 1 0 = do not allow this guest to book your properties again, 1 = allow this guest to book your property in future

Example request: guest_misconduct - Breaking House Rules

The request below reports reservation as guest misconduct with: category #7 (Breaking House Rules) and subcategory #170 (Smoking)

<request>
   <reservation_id>123456789</reservation_id>
   <report>guest_misconduct</report>
   <misconduct_details>
        <category_id>7</category_id>
        <subcategory_id>170</subcategory_id>
        <details_text>Guest was smoking in the room.</details_text>
        <escalate_report>0</escalate_report>
        <rebooking_allowed>1</rebooking_allowed>
   </misconduct_details>
</request>

Example request: guest_misconduct - Property damage

The request below reports reservation as guest misconduct with: category #9 (Property damage).

Please note that this category has no subcategories, so no subcategory_id provided.

<request>
   <reservation_id>123456789</reservation_id>
   <report>guest_misconduct</report>
   <misconduct_details>
        <category_id>9</category_id>
        <details_text>Guest left the property dirty and one of chairs was broken.</details_text>
        <escalate_report>1</escalate_report>
        <rebooking_allowed>0</rebooking_allowed>
   </misconduct_details>
</request>

Example responses: guest_misconduct

Success

<status>ok</status>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY==] -->

Error - subcategory_id is invalid

<reporting>
    <fault code="400">
        <string>Misconduct `subcategory_id` is invalid or subcategory does not belong to selected `category_id`</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY==] -->

Error - details_text is too long

<reporting>
    <fault code="400">
        <string>Misconduct `details_text` cannot exceed 240 characters</string>
    </fault>
</reporting>
<!-- RUID: [YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY==] -->

Reference tables

Request body

Field Description Type Occurrences Notes
request Root element. object 1..1 -
reservation_id The ID of the reservation you want to mark as having an invalid credit card. integer 1..1 You must have permission to edit this reservation.
report The type of report. enum 0..1 Accepts: cc_is_invalid, cancel_reservation_invalid_cc, is_no_show
report[@waived_fees] Specifies whether the property will waive the no-show fees. enum 0..1 Only allowed when value of report is is_no_show. Accepts: yes, no. Default: no
stay_change Parent element for changed stay details. string 0..* -
roomreservation_id The Booking.com ID for the room booked within the reservation (provided in the original reservation message). integer 0..1 Required if stay_change exists. The room must belong to the reservation specified in reservation_id.
checkin The new check-in date for the changed stay, in ISO 8601 YYYY-MM-DD format. date (YYYY-MM-DD) 0..1 Default: current check-in date.
checkout The new check-out date for the changed stay, in ISO 8601 YYYY-MM-DD format. date (YYYY-MM-DD) 0..1 Required if stay_change exists. Date must be after check-in date.
price The new price for changed stay, in the currency defined for the property by Booking.com. integer 0..1 Non-negative integer.
is_no_show Specifies the room reservations to mark as guest no-show. object 0..* Required if value of report is is_no_show.
is_no_show[@roomreservation_id] The Booking.com ID for the room in the reservation (provided in the original reservation message). integer 0..1 The room must belong to the reservation you specified in reservation_id.
is_no_show[@waived_fees] Specifies whether the property will waive the no-show fees. enum 0..1 Accepts: yes, no. Default: no
misconduct_details Object containing additional information for guest misconduct report type. object 0..1 For details and structure see the misconduct_details structure.