The Holibob API - Cancellation Policies

Introduction

A product’s cancellation policy defines the consequence to a consumer of cancelling a booking availability.

For information about Expedia product's cancellation policies please check this document.

Holibob API Relevant Fields

The following tables explain where in the Holibob API cancellation policies can be found.

Effective Refund Amounts

Query	Path	Description
`booking`	`booking.cancellationEffectiveRefundAmount`	This field returns the refund amount if the entire `Booking` was cancelled at that moment. This field is `null` if the `Booking` does not contain an `Availability` which can be cancelled.
`booking`	`booking.availabilityList.nodes[*].cancellationState.effectiveRefundAmount`	This field returns the refund amount if the single `BookingAvailability` was cancelled at that very moment. This field is `null` if the `BookingAvailability` can not be cancelled.

Effective Cancellation Policy

Query	Path	Description
`booking`	`booking.availabilityList.nodes[*].cancellationState.effectivePenalty`	This field returns the appropriate penalty from the penalty list if the `BookingAvailability` was cancelled at that very moment.

Cancellation Penalty Lists

Most products have a generic cancellation policy, which can be found on the Product query and is translated into the BookingAvailability when the booking is made.

Query	Path	Description
`product`	`product.cancellationPolicy.penaltyList`	This is the cancellation policy for the product. This may change as the supplier chooses to update it.
`booking`	`booking.availabilityList.nodes[*].cancellationPenaltyList`	This is the cancellation policy for the product at the time of booking. This will never change.

Understanding a Cancellation Policy

A Cancellation Policy contains a list of Cancellation Penalties

A product’s cancellation policy is made of a list of cancellation penalties. Each cancellation penalty contains the data required to calculate:

the range of cancellation dates for which this penalty is applicable
the refund amount issued to the consumer

Cancellation Date Ranges

A cancellation penalty contains a duration field formatted in the ISO 8601 standard.
The duration field can be used to calculate the range of cancellation dates applicable to that penalty.
The relativeTo field dictates what date the duration is measured from and can take the value of TRAVEL_DATE or BOOKING_DATE. The relativeTo field will always be the same for all cancellation penalties inside a cancellation policy.
If a cancellation penalty has a duration of null then this penalty becomes the exception.

Refund Amount

the type field dictates whether the refund amount is an absolute value or calculated as a percentage of the price paid. It can take the value of PERCENTAGE or ABSOLUTE.
the amountType field dictates whether the amount is a refund or a charge and can take the value of REFUND or CHARGE.

Formatted Text

The data that powers cancellation policies is complicated so we generate a formattedText field at runtime in the language requested which can be used to present on the UI.

Examples

In the following examples we refer to “Booking Date” and “Travel Date”. These are specific to the BookingAvailability and can be found in the following places:

Booking Date	`booking.availabilityList.nodes[*].createdAt`
Travel Date	`booking.availabilityList.nodes[*].startAt`

1. Percentage Refund Relative to the Travel Date

Data

Booking Date

2024-08-10 08:00:00 UTC

Travel Date

2024-08-17 12:00:00 UTC

Cancellation Penalty List

JSON

[
	{
		"type": "PERCENTAGE",
		"relativeTo": "TRAVEL_DATE",
		"duration": null,
		"refundPercentage": 100,
		"amount": null,
		"amountType": null,
		"amountCurrency": null
	},
	{
		"type": "PERCENTAGE",
		"relativeTo": "TRAVEL_DATE",
		"duration": "PT48H",
		"refundPercentage": 50,
		"amount": null,
		"amountType": null,
		"amountCurrency": null
	},
	{
		"type": "PERCENTAGE",
		"relativeTo": "TRAVEL_DATE",
		"duration": "PT24H",
		"refundPercentage": 0,
		"amount": null,
		"amountType": null,
		"amountCurrency": null
	}
]

Calculations

Cancellation Date Ranges

Penalty

Duration

Range of Cancellation Dates

Refund Amount

Penalty 1

null

From booking date than 48 hours before the travel date

2024-08-10 08:00:00 UTC to 2024-08-15 12:00:00 UTC

100%

Penalty 2

PT48H

From 48 hours before the travel date to 24 hours before the travel date

2024-08-15 12:00:00 UTC to 2024-08-16 12:00:00 UTC

50%

Penalty 3

PT24H

From 24 hours before the travel date to travel date

2024-08-16 12:00:00 UTC to 2024-08-17 12:00:00 UTC

0%

Free Cancellation / Full Refund

If this availability is cancelled before 2024-08-15 12:00:00 UTC then the consumer has free cancellation.

Partial Refund

If this availability is cancelled between 2024-08-15 12:00:00 UTC and 2024-08-16 12:00:00 UTC then the consumer is issued a partial refund.

Non-Refundable

If this availability is cancelled after 2024-08-16 12:00:00 UTC then this availability is non-refundable.

2. Absolute Refund Relative to the Booking Date

Data

Booking Date	`2024-08-10 08:00:00 UTC`
Travel Date	`2024-08-17 12:00:00 UTC`
Total Price	`£80`
Cancellation Penalty List	JSON `[ { "type": "ABSOLUTE", "relativeTo": "BOOKING_DATE", "duration": "PT24H", "refundPercentage": null, "amount": 80, "amountType": "REFUND", "amountCurrency": "GBP" }, { "type": "ABSOLUTE", "relativeTo": "BOOKING_DATE", "duration": "PT48H", "refundPercentage": null, "amount": 40, "amountType": "REFUND", "amountCurrency": "GBP" }, { "type": "ABSOLUTE", "relativeTo": "BOOKING_DATE", "duration": null, "refundPercentage": null, "amount": 0, "amountType": "REFUND", "amountCurrency": "GBP" } ]`

Calculations

Cancellation Date Ranges

Penalty

Duration

Range of Cancellation Dates

Refund Amount

Penalty 1

PT24H

From booking date than 24 hours after the booking date

2024-08-10 08:00:00 UTC to 2024-08-11 08:00:00 UTC

£80

Penalty 2

PT48H

From 24 hours after the booking date to 48 hours before the booking date

2024-08-11 08:00:00 UTC to 2024-08-12 08:00:00 UTC

£50

Penalty 3

null

From 48 hours after the booking date to travel date

2024-08-12 08:00:00 UTC to 2024-08-17 12:00:00 UTC

£0

Free Cancellation / Full Refund

If this availability is cancelled before 2024-08-11 08:00:00 UTC then the consumer has free cancellation.

Partial Refund

If this availability is cancelled between 2024-08-11 08:00:00 UTC and 2024-08-12 08:00:00 UTC then the consumer is issued a partial refund.

Non-Refundable

If this availability is cancelled after 2024-08-12 08:00:00 UTC then this availability is non-refundable.