Overview

You'll need to understand a few important concepts to get started with using the Duffel Stays API.

This guide outlines a few of the key concepts that you will need to understand before building a product on the Duffel Stays API.

Duffel has a single data model for accommodation across all Stays endpoints. This consists of three core elements:

The physical property the guest is staying at.

Includes descriptive information, including location, photos, descriptions, amenities, etc.

The room being booked.

Includes descriptive name, bed configuration, and photos.

The conditions under which the room is booked, with information on included services, cancellation policy, payment requirements, hotel policy information.

One rate is distinguishable from another based on a specific rate characteristics. These characteristics are defined by the accommodation providers to specifically suit different travellers buying preferences.

You should consider how each of these affects the relevancy of the rate to your customer and whether it’s something you want to present to your customers to aid their buying decision between different rates.

These include:

A rate is considered the exact same if it has identical information across these characteristics. If the same accommodation offers the same exact rate for a given room across multiple sources, then Duffel discards all rates except the cheapest rate by default.

The possible refunds, once this rate has been booked. These can be categorised into three buckets:

Fully refundable - The full amount paid will be refunded on cancellation.

Partially refundable - Part of the amount paid will be refunded on cancellation.

Non-refundable - No refund is available on cancellation.

The refund-ability of a rate usually changes as you get closer to check-in. We express this in the form of a cancellation timeline, where you can see what refund-ability terms apply at any given time prior to check-in.

For more information on how to display the cancellation timeline, please read the Displaying the cancellation timeline implementation guide.

Board type refers to the meals and drinks that are included in the price of the rate.

The full list of support board types are outlined in the API reference.

The form of payment that can be used to pay for the rate. This characteristic is the only one that is not presented to your customer. It is instead provided to you to determine which rates that are suitable to present to your customer based on your payment or monetisation strategy.

The full list of support board types are outlined in the API reference.

Loyalty programmes allow customers to earn points when making a booking, as well as potentially access member benefits on arrival, such as free Wi-Fi, late checkouts and gifts.

For a given accommodation, only a subset of rates may support the ability to earn loyalty points on a booking.

For more information on how to work with Stays loyalty programmes, please read the Booking with Loyalty implementation guide.

The total price for the room for all nights and for all guests. This includes base rate, and all taxes and fees due at time of booking.

If you'd like to get a complete look at data you have available when presenting accommodation, room and rates to customers, check out our API reference.