Displaying the Cancellation Timeline

It's important you convey what's included in an accommodation rate to ensure your customers make informed purchasing decisions when planning their travel.
Accommodation rates refer to the cost of staying at an accommodation, what services may or may not be included in the price, and the applicable booking conditions. The rate is typically determined by the accommodation owner based on a variety of factors, such as the season, location, room type, amenities, availability, and cancellation policies.
This guide explains one way to convey the cancellation policy using the Duffel Stays API and, in the event a booking is cancelled, what refund they are eligible for.

Live demo

Understanding the data

Each rate includes a cancellation_timeline containing policies such as possible refunds. Generally, a cancellation timeline may contain the following items:

Full refund

  • When cancellation_timeline.refund_amount is the same as rate.total_amount.

  • This is only available up until the before date

Partial refund

  • Whencancellation_timeline.refund_amount is less than rate.total_amount.

  • This is only available up until the before date (after the previous before date, if any)

  • There may be multiple partial refund items

No refund

  • This item is not guaranteed to be part of the cancellation_timeline list

  • If the last cancellation timeline’s before date is before the check-in date, the time period after that is non-refundable.

  • If the cancellation_timeline is an empty list, the rate is not refundable either.

note

Visualising the cancellation timeline effectively

To better illustrate the cancellation timeline, the Duffel Dashboard displays it as a series of small timeline items lined up next to each other, as shown below.
Cancellation timeline

Cancellation timeline

To break it down, this whole timeline is simply a series of small timeline items lining up next to each other. In this example we refer to this as TimelineItem.
interface TimelineItemProps {
// whether the line should have a dot
hasDot?: boolean
// dot color
dotColor?: Color
// line color on the left
lineColorLeft?: Color
// line color on the right
lineColorRight?: Color
// bold text below the dot
label?: string
// text below the label
description?: string
// text (or items) above the dot
aboveDot?: string | React.ReactNode
}
Here's a visual of the timeline item:
Cancellation timeline item

Cancellation timeline item

Each cancellation_timeline item is rendered as two timeline items side by side, as shown in the following code snippet:

React

/*
* Connect to the section to the left; In this case, it's the first section
* so it's just the grey color
*/
<TimelineItem
hasDot={true}
dotColor="green"
lineColorLeft="grey"
lineColorRight="green"
label="Booking"
/>
/* The simple line section to extend until the next section */
<TimelineItem
hasDot={false}
lineColorLeft="green"
lineColorRight="green"
label="Full refund"
description="US$1209.18"
/>
With this simple logic, a timeline can be built to communicate refunds and deadlines to your customer visually. You can find the code in the CodeSandbox here. We will also be providing this component as part of Duffel Components library soon. Meanwhile, we hope that this guide can help you implement this for your own application. Happy coding!