When estimating refunds, you must always check against the data populated in cancelPolicyInfoList.

If the customer cancels within the hotel's cancellation policy window, you must first calculate the cancellation penalty and subtract it from the total attribute of ChargeableRateInfo.

If the customer cancels outside of the policy window, simply return the value of the ChargeableRateInfo total attribute as the estimated refund.

Whenever you return estimates for display to customers, always use clear messaging stating it is an estimate only with no express or implied guarantees. Realtime price updates, discounts applied after the initial booking, etc, cannot be accounted for in the API.

Only EAN customer support agents are able to see exact amounts to be refunded. Call your region's support number to obtain a precise amount.

Calculating and applying cancellation penalities to estimates

This section refers to information contained in cancelPolicyInfoList. You should fully familiarize yourself with the structure of this array before attempting to implement refund estimations. To determine if a penalty applies to a cancellation, first check if the value of the startWindowHours element in the second cancelPolicyInfo node.

If the time of the cancellation request falls within the window, you must calculate and subtract the penalty from your estimate. If not, simply return the total value originally charged as your estimate.

To calculate the penalty, refer to the values of the penalty detail elements returned in the first cancelPolicyInfo node.

Examples:

<CancelPolicyInfoList>
 <CancelPolicyInfo>
   <versionId>0</versionId>
   <cancelTime>19:00:00</cancelTime>
   <startWindowHours>0</startWindowHours>
   <amount>50</amount>
   <currencyCode>USD</currencyCode>
   <timeZoneDescription>(GMT-06:00)</timeZoneDescription>
 </CancelPolicyInfo>
 <CancelPolicyInfo>
  <versionId>0</versionId>
  <cancelTime>19:00:00</cancelTime>
  <startWindowHours>48</startWindowHours>
  <amount>0</amount>
  <currencyCode>USD</currencyCode>
  <timeZoneDescription>(GMT-06:00)</timeZoneDescription>
</CancelPolicyInfo>
</CancelPolicyInfoList>

startWindowHours in the second node returned with a value of 48. Customer cancels 46 hours before the start of their stay. You must subtract $50 USD from the total charged at booking time to properly calculate your estimate.

Each cancelPolicyInfo node may contain amount, percent, or nightCount individually, or combinations of amount & nightCount or amount & percent.

Any other combination within a single node is invalid and should be treated as an error. Ignore elements that return empty or with 0, as they do not contribute to the policy calculation.

Remember that it is possible for policies to have penalties both inside and outside of the window (positive values in both the first and second nodes). It is uncommon, but as long as any combination of penalty values is valid as described above, the entire policy is still valid.

Penalty calculations and examples

These penalty examples cover all possible valid combinations you can expect from the API. In most cases, you only need calculate penalties for cancellations made inside of the policy window. However, in some cases, you may need to calculate penalties for cancellations outside the window as well – see the last example on this page.

When calculating the tax for individual nightly rates, remember to calculate the tax ratio using the nightlyRateTotal, not total. This is to help build your estimate only - this is not how EAN calculates tax for refunds.


Note that tax values subtracted for night penalty calculations are per-night , not total values.

Refer to the following rates and totals for all examples below:

<ChargeableRateInfo {truncated} total="983.34" nightlyRateTotal="816.05">
    <NightlyRatesPerRoom size="2">
        <NightlyRate baseRate="400.58" rate="400.58" promo="false"></NightlyRate>
        <NightlyRate baseRate="415.47" rate="415.47" promo="false"></NightlyRate>
    </NightlyRatesPerRoom>
<Surcharges size="1">
    <Surcharge type="TaxAndServiceFee" amount="167.29"></Surcharge>
</Surcharges>

Calculating a refund with a cancellation penalty amount value of 50

  • total - amount
  • 983.34 - 50= 933.34 estimated refund

Calculating a refund with a cancellation penalty percent value of 25

  • total - (% of total)
  • 983.34 - (25% of 983.34)= 737.50 estimated refund

Calculating a refund with a cancellation penalty nightCount value of 1

  • total - (first nightly rate value + first night's tax)
  • 983.34 - (400.58 + 82.12)= 500.64 estimated refund

Calculating a refund with a cancellation penalty nightCount value of 2

  • total - ([first nightly rate value + first night's tax]+[second nightly rate value + second night's tax])
  • 983.34 - ([400.58 + 82.12] + [415.47 + 85.17]) = 0.00 (no refund after penalty)

Calculating a refund with a cancellation penalty amount value of 20 and a percent value of 10

  • total - amount - (% of total)
  • 983.34 - 20 - (10% of 983.34)= 865.01 estimated refund

Calculating a refund with a cancellation penalty amount value of 30 and a nightCount value of 1

  • total - (amount + [first nightly rate value + first night's tax])
  • 983.34 - (30 + [400.58 + 82.12]) = 470.64 estimated refund


Penalties inside and outside the policy window

The example cancellation policy below establishes penalties for canceling both inside and outside of the policy window. Example calculations use the same rate and total values as previous examples.

<CancelPolicyInfoList> 
 <CancelPolicyInfo>
  <versionId>0</versionId>
<cancelTime>23:59:00</cancelTime>
<startWindowHours>0</startWindowHours>
<nightCount>0</nightCount>
<percent>100</percent>
<currencyCode>USD</currencyCode>
<timeZoneDescription>(GMT+08:00) </timeZoneDescription> </CancelPolicyInfo>

<CancelPolicyInfo>
<versionId>0</versionId>
<cancelTime>23:59:00</cancelTime>
<startWindowHours>168</startWindowHours>
<nightCount>1</nightCount>
<currencyCode>USD</currencyCode>
<timeZoneDescription>(GMT+08:00)</timeZoneDescription>
</CancelPolicyInfo>
</CancelPolicyInfoList>

Calculating a refund inside of the window (customer cancels within 168 hours or less before check-in):

  • total - (% of total)
  • 983.34 - (100% of 983.34)= 0 estimated refund

Calculating a refund outside of the window (customer cancels any time before the 168 hour policy window begins):

  • total - (first nightly rate value + first night's tax)
  • 983.34 - (400.58 + 82.12) = 500.64