Constructing cancellation policies

Understand more about how cancellation policies work on the Rapid API.

Introduction

All rate types that are not fully refundable at time of booking will display refundable=false in the API response.

The specific cancellation policy for each rate is determined by a combination of the cancel_penalties and the nonrefundable_date_ranges objects in the Rapid Shop Availability API.

  • The nonrefundable_date_ranges object defines any stay dates that are completely non-refundable at time of booking. As such, this object takes precedence over any additional cancellation policies set out in the cancel_penalties object. Using the nonrefundable_date_ranges object to set stay dates that are non-refundable at time of booking is optional. Please note, the nonrefundable_date_range is inclusive, i.e. the nightly rate plus any taxes and fees for the 'end' date will also be charged.
  • The cancel_penalties object sets out any additional cancellation penalty details and there are a variety of options to construct these policies. The details include the start date and end date of the specified penalty window as well as the penalty type and value. The penalty types include a fixed amount, number of nights, and percentage of total cost.

It is important to note that where a rate has non-refundable dates defined in the nonrefundable_date_ranges object these nights will be charged in addition to any other cancellation penalty charges set out in the cancel_penalties object.

The refund amount for a booking can be found in the cancel_refund object within the Retrieve Booking service as part of the Manage Booking API. See below for more detail on the refund status of per-stay amounts.

Note: The timezone of the cancel_penalties start and end window is the local property time.

The following guidelines for constructing the cancellation policy text are provided to help properties interpret and communicate the cancellation policy accurately to the end traveler, or display a non-refundable message to customers when the API returns the policy in a format that is not listed.

Policy template

The cancellation policy is comprised of four major time frames that are represented with the following template. Include all four time frames to properly represent the cancellation policy.

1. Cancellation policy exception time frame.

Dates for which no refund will be given upon cancellation, from time of booking, can be defined in the nonrefundable_date_ranges object. Stay dates that fall outside of this window are subject to the policy given in within the cancel_penalties object and therefore it is possible to receive a partial refund if only part of the stay booked falls within the exception time frame.

2. Free cancellation time frame.

Free cancellation until [start date time of the earliest penalty window]. Note, booked stay dates that fall within a non-refundable date range (as defined in the nonrefundable_date_ranges object) will not be refunded but any stay dates outside of this period will be refunded in full if cancellation is made prior to the start time of the earliest penalty window given in the cancel_penalties object.

3. Penalty cancellation time frames (multiple penalty time frames are possible) if cancel_penalties is in the API response.

Note: Booked stay dates that fall within a non-refundable date range (as defined in the nonrefundable_date_ranges object) will still be charged in full but any stay dates outside of this period will be refunded in line with policies given in the cancel_penalties object.

Amount penalty

Cancellations made after [start date time of penalty window] will result in an [amount] [currency] fee.

OR

Night penalty

Cancellations made after [start date time of penalty window] are subject to a [number of nights] night(s) penalty plus taxes and fees.

OR

Percent penalty

Cancellations made after [start date time of penalty window] are subject to a [percentage] percentage of total price penalty. It is possible to have penalties of both amount and night or amount and percent, but not a night and percent penalty in the same time frame.

4. Late check-in and no-show time frame.

If you fail to check-in for this reservation, or if you cancel or change this reservation after check-in, you may incur penalty charges at the discretion of the property of up to 100% of the booking value.

The end date of the latest penalty window is the latest cancellation date and time.

5. Refunds for per-stay amounts.

Per-stay amounts, returned in the stay object, are considered non-refundable if one or more days of stay are also non-refundable. Per-stay amounts will only be refunded if the entire stay is fully refundable.

Examples

|

Example 1 - Amount penalty

API response:

"refundable": true,
"cancel_penalties": [
    {
        "start": "2022-08-26T23:59:00.000+07:00",
        "end": "2022-09-29T23:59:00.000+07:00",
        "amount": "
        ",
        "currency": "USD"
    }
],

Booking details:

  • Customer makes booking on 5 July 2022
  • Check-in date is 29 September 2022
  • Check-out date is 6 October 2022

Cancellation policy explained:

  • Free cancellation until 26 August 2022 11:59 PM (GMT +7:00).
  • Cancellations made after 26 August 2022 11:59 PM (GMT +7:00) will result in a 200 USD fee.
  • The end time for the cancellation window is 29 September 11:59 PM (GMT +7:00) at which time the booking will become fully non-refundable.
  • If you fail to check in for this reservation, or if you cancel or change this reservation after check-in, you may incur penalty charges at the discretion of the property of up to 100% of the booking value.

Note: In case of multiple room request, cancel penalty amount returned is per room occupancy type and should be multiplied accordingly.

Example 2 - Amount penalty + non-refundable dates

API response:

"refundable": false,
"cancel_penalties": [
    {
        "start": "2022-08-26T23:59:00.000+07:00",
        "end": "2022-09-29T23:59:00.000+07:00",
        "amount": "200",
        "currency": "USD"
    }
], 
"nonrefundable_date_ranges": [ 
    {  
        "start": "2022-09-30",
        "end": "2022-10-01"
    }
    {   "start": "2022-10-05",         
        "end": "2022-10-06"     
    }
],

Booking details:

  • Customer makes booking on 5 July 2022
  • Check-in date is 29 September 2022
  • Check-out date is 7 October 2022

Cancellation policy explained:

  • Cancellation before 26 August 2022 11:59 PM (GMT +7:00):
    • Any booked nights during non-refundable date ranges (30 September 2022 - 1 October 2022 and 5 October 2022 - 6 October 2022) are completely non-refundable from time of booking.
    • Cancellation is free for any nights that fall outside of the non-refundable date ranges.
  • Cancellations between 26 August 2022 11:59 PM (GMT +7:00) and 29 September 2022 11:59 PM (GMT +7:00):
    • Any booked nights during the non-refundable date ranges (30 September 2022 - 1 October 2022 and 5 October 2022 - 6 October 2022) are completely non-refundable from time of booking.
    • There will be a 200 USD penalty charge in addition to any nights which are non-refundable.
  • The end time for the cancellation window is 29 September 11:59 PM (GMT +7:00) at which time the booking will become fully non-refundable.
  • If you fail to check in for this reservation, or if you cancel or change this reservation after check-in, you may incur penalty charges at the discretion of the property of up to 100% of the booking value.

Note:

  • The nonrefundable_date_ranges object can be combined in this way with any of the cancel_penalties object time frames.
  • In case of multiple room request, cancel penalty amount returned is per room occupancy type and should be multiplied accordingly.

Example 3 - Night penalty

API response:

"refundable": true,
"cancel_penalties": [
    {
        "start": "2022-08-26T23:59:00.000+07:00",
        "end": "2022-09-29T23:59:00.000+07:00",
        "nights": "1",
        "currency": "USD"
    }
],

Booking details:

  • Customer makes booking on 5 July 2022
  • Check-in date is 29 September 2022
  • Check-out date is 6 October 2022

Cancellation policy explained:

  • Free cancellation until 26 August 2022 11:59 PM (GMT +7:00).
  • Cancellations made after 26 August 2022 11:59 PM (GMT +7:00) will result in a 1 night penalty charge.
  • The end time for the cancellation window is 29 September 11:59 PM (GMT +7:00) at which time the booking will become fully non-refundable.
  • If you fail to check in for this reservation, or if you cancel or change this reservation after check-in, you may incur penalty charges at the discretion of the property of up to 100% of the booking value.

Note: Where multiple nights are booked, the penalty charge taken will be for the first night of the reservation.

Example 4 - Percent penalty

API response:

"refundable": true,
"cancel_penalties": [
    {         
        "start": "2022-08-26T23:59:00.000+07:00",        
        "end": "2022-09-29T23:59:00.000+07:00",         
        "percent": "90%",        
        "currency": "USD"     }
],

Booking details:

  • Customer makes booking on 5 July 2022
  • Check-in date is 29 September 2022
  • Check-out date is 6 October 2022

Cancellation policy explained:

  • Free cancellation until 26 August 2022 11:59 PM (GMT +7:00).
  • Cancellations made after 26 August 2022 11:59 PM (GMT +7:00) will result in a 90% penalty of the stay charges and fees.
  • The end time for the cancellation window is 29 September 2022 11:59 PM (GMT +7:00) at which time the booking will become fully non-refundable.
  • If you fail to check in for this reservation, or if you cancel or change this reservation after check-in, you may incur penalty charges at the discretion of the property of up to 100% of the booking value.

Example 5 - Free cancellation/no cancel penalties

API response:

"refundable": true,
"cancel_penalties": [
    {
    "start": "2022-08-26T23:59:00.000+07:00",
    "end": "2022-09-29T23:59:00.000+07:00",
    "nights": "0",
    "currency": "USD"
    }
],

Booking details:

  • Customer makes booking on 5 July 2022
  • Check-in date is 29 September 2022
  • Check-out date is 6 October 2022

Cancellation policy explained:

  • Free cancellation until 26 August 2022 11:59 PM (GMT +7:00).
  • Cancellation between 26 August 11:59 PM (GMT +7:00) and the day of check-in, 29 September 2022, is free of charge. No penalty charge will be incurred.
  • If you fail to check in for this reservation, or if you cancel or change this reservation after check-in, you may incur penalty charges at the discretion of the property of up to 100% of the booking value.

Example 6 - Non-refundable

If a booking is fully non-refundable, the start date/time of the cancel_penalties window will be before the booking date/time.

API response:

"cancel_penalties": [
        {
                "start": "2022-11-29T10:47:19.727+00:00",
                "end": "2023-01-05T23:59:00.000+00:00",
                "percent": "100%",
                "currency": "USD"
        }
    ],

Booking details:

  • Customer makes booking on 30 November 2022
  • Check-in date is 5 January 2023
  • Check-out date is 7 January 2023

Cancellation policy text:

  • If you cancel your reservation, you will not get a refund or credit to use for a future stay.

Example 7 - Tiered cancellation

Tiered cancellation policies allow properties to charge customers a cancellation penalty that varies according to the amount of notice given of cancellation. Usually, the closer the customer cancels to their stay date, the higher the cancellation penalty will be.

API response:

"refundable": true,
"cancel_penalties": [
    { 
        "start": "2022-08-31T23:59:00.000+07:00",
        "end": "2022-12-09T23:59:00.000+07:00",
        "percent": "70%", 
        "currency": "USD" 
    },
    { 
        "start": "2022-12-09T23:59:00.000+07:00",
        "end": "2022-12-12T23:59:00.000+07:00",
        "percent": "90%", 
        "currency": "USD" 
    }
 ],

Booking details:

  • Customer makes booking on 5 July 2022
  • Check-in date is 12 December 2022
  • Check-out date is 22 December 2022

Cancellation policy explained:

  • Cancellations prior to 31 August 2022 11:59 PM (GMT +7:00) are free.
  • Cancellations between 31 August 2022 11:59 PM (GMT +7:00) and 9 December 2022 11:59 PM (GMT +7:00) will result in a 70% penalty of the stay charges and fees.
  • Cancellations between 9 December 2022 11:59 PM (GMT +7:00) and 12 December 2022 11:59 PM (GMT +7:00) will result in a 90% penalty of the stay charges and fees.
  • The end time for the cancellation window is 12 December 2022 11:59 PM (GMT +7:00) at which time the booking will become fully non-refundable.
  • If you fail to check in for this reservation, or if you cancel or change this reservation after check-in, you may incur penalty charges at the discretion of the property of up to 100% of the booking value.

Example 8 - Partially refundable

API response:

"refundable": false
"cancel_penalties": [
     {
     "start": "2022-11-27T22:21:15.996+01:00",
     "end": "2023-01-10T18:00:00.000+01:00",
     "percent": "90%",
     "currency": "USD"
     }
  ],

Booking details:

  • Customer makes booking on 28 November 2022
  • Check-in date is 10 January 2023
  • Check-out date is 14 January 2023

Cancellation policy explained:

  • All cancellations from time of booking will incur a 90% cancellation penalty charge.
  • The end time for the cancellation window is 10 January 2023 00:00 AM (GMT +1:00) at which time the booking will become fully non-refundable.
  • If you fail to check in for this reservation, or if you cancel or change this reservation after check-in, you may incur penalty charges at the discretion of the property of up to 100% of the booking value.

Example 9 - Non-refundable per-stay amounts

API response:

"refundable" : true,
      "cancel_refund" : {
        "amount" : "-784.57",
        "currency" : "EUR"
      },
      "cancel_penalties" : [ {
        "currency" : "EUR",
        "nights" : "1",
        "start" : "2022-11-16T18:00:00.000+04:00",
        "end" : "2022-11-19T18:00:00.000+04:00"

Cancellation policy explained:

  • Per-stay amounts are only refundable where the entire reservation is refundable.
  • Cancellation of this booking incurs a 1 night cancellation penalty, therefore the entire reservation is not refundable, any per-stay amounts would not be refunded in this instance.
Did you find this page helpful?
How can we improve this content?
Thank you for helping us improve!