Bookings
A reservation with the stay for the room(s) requested from a quote
Schema
The ISO 8601 datetime of the cancellation of this booking. This is null
if the booking is not yet cancelled.
null
The ISO 8601 datetime at which the booking was made.
"2023-04-13T15:48:11.642Z"
The loyalty programme account number provided for the Booking when the create Booking endpoint was called.
Account number is relayed to the hotel on a best-effort basis, it is at the hotel's discretion to honour the loyalty programme.
"201154908"
The metadata associated with this booking. The structure of this is not defined and is used to attach additional keys and values to the booking. This is used by Duffel Links to tag bookings created by a specific Links session. See the Duffel Links documentation for more information.
{"checkout_reference":"usr_0000AePJGl5G9ZYfmNllrs"}
Lead guest's phone number in E.164 (international) format.
"+442080160509"
The loyalty programme that this booking supports.
"wyndham_rewards"
, "choice_privileges"
, "marriott_bonvoy"
, "best_western_rewards"
, "world_of_hyatt"
, "hilton_honors"
, "ihg_one_rewards"
, "leaders_club"
, "stash_rewards"
, "omni_select_guest"
, "i_prefer"
, "accor_live_limitless"
, "my_6"
, "jumeirah_one"
, "global_hotel_alliance_discovery"
, or "duffel_hotel_group_rewards"
Endpoint
POST https://api.duffel.com/stays/bookings/{booking_id}/actions/cancel
Request
curl -X POST --compressed "https://api.duffel.com/stays/bookings/{booking_id}/actions/cancel" \-H "Accept-Encoding: gzip" \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Duffel-Version: v2" \-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"
Response
{"data": {"users": ["icu_00009htyDGjIfajdNBZRlw"],"supported_loyalty_programme": "duffel_hotel_group_rewards","status": "cancelled","rooms": 1,"reference": "AFE33SE2","phone_number": "+442080160509","metadata": {"checkout_reference": "usr_0000AePJGl5G9ZYfmNllrs"},"loyalty_programme_account_number": "201154908","id": "bok_0000BTVRuKZTavzrZDJ4cb","guests": [{"user_id": "icu_00009htyDGjIfajdNBZRlw","given_name": "Amelia","family_name": "Earhart"}],"email": "amelia.earheart@duffel.com","confirmed_at": "2023-04-13T15:48:11.642Z","check_out_date": "2023-05-28","check_in_date": "2023-05-24","cancelled_at": "2023-04-14T15:48:11.642Z","accommodation": {"supported_loyalty_programme": "duffel_hotel_group_rewards","rooms": [{"rates": [{"total_currency": "GBP","total_amount": "799.00","tax_currency": "GBP","tax_amount": "82.23","supported_loyalty_programme": "duffel_hotel_group_rewards","quantity_available": 12,"public_currency": "GBP","public_amount": "699.99","payment_type": "pay_now","id": "rat_0000BTVRuKZTavzrZDJ4cb","fee_currency": "GBP","fee_amount": "50.94","due_at_accommodation_currency": "GBP","due_at_accommodation_amount": "39.95","deal_types": ["closed_user_group","mobile"],"conditions": [{"title": "Parking","description": "Public parking is available nearby for £15 per day"}],"cancellation_timeline": [{"refund_amount": "799.00","currency": "GBP","before": "2023-05-23T13:00:00Z"}],"board_type": "room_only","base_currency": "GBP","base_amount": "665.83","available_payment_methods": [["balance"]]}],"photos": [{"url": "https://assets.duffel.com/img/stays/image.jpg"}],"name": "Double Suite","beds": [{"type": "king","count": 2}]}],"review_score": 8.8,"rating": 3,"photos": [{"url": "https://assets.duffel.com/img/stays/image.jpg"}],"phone_number": "+442074938181","name": "Duffel Test Hotel","location": {"geographic_coordinates": {"longitude": -0.1416,"latitude": 51.5071},"address": {"region": "England","postal_code": "EC2A 4TP","line_one": "100 Clifton Street","country_code": "GB","city_name": "London"}},"key_collection": {"instructions": "Please collect the keys from accommodation's reception."},"id": "acc_0000AWr2VsUNIF1Vl91xg0","email": "reservations@duffel-hotel-group.com","description": "Ornate quarters, some with grand pianos, in a luxurious hotel offering acclaimed dining & a spa.","check_in_information": {"check_out_before_time": "11:30","check_in_before_time": "00:00","check_in_after_time": "14:30"},"chain": {"name": "Duffel Hotel Group"},"brand": {"name": "Duffel Test","id": "bra_0000Alr8BYNsbmDMThHSbI"},"amenities": [{"type": "parking","description": "Parking"}]}}}
Endpoint
GET https://api.duffel.com/stays/bookings/{id}
Request
curl -X GET --compressed "https://api.duffel.com/stays/bookings/{id}" \-H "Accept-Encoding: gzip" \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Duffel-Version: v2" \-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"
Response
{"data": {"users": ["icu_00009htyDGjIfajdNBZRlw"],"supported_loyalty_programme": "duffel_hotel_group_rewards","status": "confirmed","rooms": 1,"reference": "AFE33SE2","phone_number": "+442080160509","metadata": {"checkout_reference": "usr_0000AePJGl5G9ZYfmNllrs"},"loyalty_programme_account_number": "201154908","id": "bok_0000BTVRuKZTavzrZDJ4cb","guests": [{"user_id": "icu_00009htyDGjIfajdNBZRlw","given_name": "Amelia","family_name": "Earhart"}],"email": "amelia.earheart@duffel.com","confirmed_at": "2023-04-13T15:48:11.642Z","check_out_date": "2023-05-28","check_in_date": "2023-05-24","accommodation": {"supported_loyalty_programme": "duffel_hotel_group_rewards","rooms": [{"rates": [{"total_currency": "GBP","total_amount": "799.00","tax_currency": "GBP","tax_amount": "82.23","supported_loyalty_programme": "duffel_hotel_group_rewards","quantity_available": 12,"public_currency": "GBP","public_amount": "699.99","payment_type": "pay_now","id": "rat_0000BTVRuKZTavzrZDJ4cb","fee_currency": "GBP","fee_amount": "50.94","due_at_accommodation_currency": "GBP","due_at_accommodation_amount": "39.95","deal_types": ["closed_user_group","mobile"],"conditions": [{"title": "Parking","description": "Public parking is available nearby for £15 per day"}],"cancellation_timeline": [{"refund_amount": "799.00","currency": "GBP","before": "2023-05-23T13:00:00Z"}],"board_type": "room_only","base_currency": "GBP","base_amount": "665.83","available_payment_methods": [["balance"]]}],"photos": [{"url": "https://assets.duffel.com/img/stays/image.jpg"}],"name": "Double Suite","beds": [{"type": "king","count": 2}]}],"review_score": 8.8,"rating": 3,"photos": [{"url": "https://assets.duffel.com/img/stays/image.jpg"}],"phone_number": "+442074938181","name": "Duffel Test Hotel","location": {"geographic_coordinates": {"longitude": -0.1416,"latitude": 51.5071},"address": {"region": "England","postal_code": "EC2A 4TP","line_one": "100 Clifton Street","country_code": "GB","city_name": "London"}},"key_collection": {"instructions": "Please collect the keys from accommodation's reception."},"id": "acc_0000AWr2VsUNIF1Vl91xg0","email": "reservations@duffel-hotel-group.com","description": "Ornate quarters, some with grand pianos, in a luxurious hotel offering acclaimed dining & a spa.","check_in_information": {"check_out_before_time": "11:30","check_in_before_time": "00:00","check_in_after_time": "14:30"},"chain": {"name": "Duffel Hotel Group"},"brand": {"name": "Duffel Test","id": "bra_0000Alr8BYNsbmDMThHSbI"},"amenities": [{"type": "parking","description": "Parking"}]}}}
Update booking
Update information on a specific booking made by your organisation.
Endpoint
PATCH https://api.duffel.com/stays/bookings/{id}
Request
curl -X PATCH --compressed "https://api.duffel.com/stays/bookings/{id}" \-H "Accept-Encoding: gzip" \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Duffel-Version: v2" \-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \-d '{"data": {"users": ["icu_00009htyDGjIfajdNBZRlw"]}}'
Response
{"data": {"users": ["icu_00009htyDGjIfajdNBZRlw"],"supported_loyalty_programme": "duffel_hotel_group_rewards","status": "confirmed","rooms": 1,"reference": "AFE33SE2","phone_number": "+442080160509","metadata": {"checkout_reference": "usr_0000AePJGl5G9ZYfmNllrs"},"loyalty_programme_account_number": "201154908","id": "bok_0000BTVRuKZTavzrZDJ4cb","guests": [{"user_id": "icu_00009htyDGjIfajdNBZRlw","given_name": "Amelia","family_name": "Earhart"}],"email": "amelia.earheart@duffel.com","confirmed_at": "2023-04-13T15:48:11.642Z","check_out_date": "2023-05-28","check_in_date": "2023-05-24","accommodation": {"supported_loyalty_programme": "duffel_hotel_group_rewards","rooms": [{"rates": [{"total_currency": "GBP","total_amount": "799.00","tax_currency": "GBP","tax_amount": "82.23","supported_loyalty_programme": "duffel_hotel_group_rewards","quantity_available": 12,"public_currency": "GBP","public_amount": "699.99","payment_type": "pay_now","id": "rat_0000BTVRuKZTavzrZDJ4cb","fee_currency": "GBP","fee_amount": "50.94","due_at_accommodation_currency": "GBP","due_at_accommodation_amount": "39.95","deal_types": ["closed_user_group","mobile"],"conditions": [{"title": "Parking","description": "Public parking is available nearby for £15 per day"}],"cancellation_timeline": [{"refund_amount": "799.00","currency": "GBP","before": "2023-05-23T13:00:00Z"}],"board_type": "room_only","base_currency": "GBP","base_amount": "665.83","available_payment_methods": [["balance"]]}],"photos": [{"url": "https://assets.duffel.com/img/stays/image.jpg"}],"name": "Double Suite","beds": [{"type": "king","count": 2}]}],"review_score": 8.8,"rating": 3,"photos": [{"url": "https://assets.duffel.com/img/stays/image.jpg"}],"phone_number": "+442074938181","name": "Duffel Test Hotel","location": {"geographic_coordinates": {"longitude": -0.1416,"latitude": 51.5071},"address": {"region": "England","postal_code": "EC2A 4TP","line_one": "100 Clifton Street","country_code": "GB","city_name": "London"}},"key_collection": {"instructions": "Please collect the keys from accommodation's reception."},"id": "acc_0000AWr2VsUNIF1Vl91xg0","email": "reservations@duffel-hotel-group.com","description": "Ornate quarters, some with grand pianos, in a luxurious hotel offering acclaimed dining & a spa.","check_in_information": {"check_out_before_time": "11:30","check_in_before_time": "00:00","check_in_after_time": "14:30"},"chain": {"name": "Duffel Hotel Group"},"brand": {"name": "Duffel Test","id": "bra_0000Alr8BYNsbmDMThHSbI"},"amenities": [{"type": "parking","description": "Parking"}]}}}
List bookings
Lists bookings made for your organisation. Returns a list of Duffel Stay Bookings.
Query parameters
A cursor pointing to the previous page of records. For more information on how to paginate through records, see the Pagination section.
"g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="
A cursor pointing to the next page of records. For more information on how to paginate through records, see the Pagination section.
"g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="
The maximum number of records to return per page.
May be set to any integer between 1
and 200
. For more information on how to paginate through records, see the Pagination section.
This endpoint will return all entries if no pagination parameters are passed.
1
Endpoint
GET https://api.duffel.com/stays/bookings
Request
curl -X GET --compressed "https://api.duffel.com/stays/bookings?after=g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB=&before=g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB=&limit=1" \-H "Accept-Encoding: gzip" \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Duffel-Version: v2" \-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"
Response
{"meta": {"limit": 50,"after": "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="},"data": [{"users": ["icu_00009htyDGjIfajdNBZRlw"],"supported_loyalty_programme": "duffel_hotel_group_rewards","status": "confirmed","rooms": 1,"reference": "AFE33SE2","phone_number": "+442080160509","metadata": {"checkout_reference": "usr_0000AePJGl5G9ZYfmNllrs"},"loyalty_programme_account_number": "201154908","id": "bok_0000BTVRuKZTavzrZDJ4cb","guests": [{"user_id": "icu_00009htyDGjIfajdNBZRlw","given_name": "Amelia","family_name": "Earhart"}],"email": "amelia.earheart@duffel.com","confirmed_at": "2023-04-13T15:48:11.642Z","check_out_date": "2023-05-28","check_in_date": "2023-05-24","accommodation": {"supported_loyalty_programme": "duffel_hotel_group_rewards","rooms": [{"rates": [{"total_currency": "GBP","total_amount": "799.00","tax_currency": "GBP","tax_amount": "82.23","supported_loyalty_programme": "duffel_hotel_group_rewards","quantity_available": 12,"public_currency": "GBP","public_amount": "699.99","payment_type": "pay_now","id": "rat_0000BTVRuKZTavzrZDJ4cb","fee_currency": "GBP","fee_amount": "50.94","due_at_accommodation_currency": "GBP","due_at_accommodation_amount": "39.95","deal_types": ["closed_user_group","mobile"],"conditions": [{"title": "Parking","description": "Public parking is available nearby for £15 per day"}],"cancellation_timeline": [{"refund_amount": "799.00","currency": "GBP","before": "2023-05-23T13:00:00Z"}],"board_type": "room_only","base_currency": "GBP","base_amount": "665.83","available_payment_methods": [["balance"]]}],"photos": [{"url": "https://assets.duffel.com/img/stays/image.jpg"}],"name": "Double Suite","beds": [{"type": "king","count": 2}]}],"review_score": 8.8,"rating": 3,"photos": [{"url": "https://assets.duffel.com/img/stays/image.jpg"}],"phone_number": "+442074938181","name": "Duffel Test Hotel","location": {"geographic_coordinates": {"longitude": -0.1416,"latitude": 51.5071},"address": {"region": "England","postal_code": "EC2A 4TP","line_one": "100 Clifton Street","country_code": "GB","city_name": "London"}},"key_collection": {"instructions": "Please collect the keys from accommodation's reception."},"id": "acc_0000AWr2VsUNIF1Vl91xg0","email": "reservations@duffel-hotel-group.com","description": "Ornate quarters, some with grand pianos, in a luxurious hotel offering acclaimed dining & a spa.","check_in_information": {"check_out_before_time": "11:30","check_in_before_time": "00:00","check_in_after_time": "14:30"},"chain": {"name": "Duffel Hotel Group"},"brand": {"name": "Duffel Test","id": "bra_0000Alr8BYNsbmDMThHSbI"},"amenities": [{"type": "parking","description": "Parking"}]}}]}
Creating a booking
To create a stay booking, select a quote and provide guest information. The booking can be paid using the Duffel balance. This action will return a Duffel Stays Booking, which will have a confirmed booking status.
If an unexpected error occurs, such as a 500 HTTP status code, and the booking status cannot be determined, do not attempt to retry the action. Instead, please contact Duffel Support for assistance with your request ID. Please see the Booking creation response handling documentation for more information on possible responses and how to handle them.
Body parameters
List of guests that will stay on this booking. A minimum of one guest must be provided. For bookings of more than one room, the reservation will be made under the name of the first guest provided. We recommend (though optional) that you pass an additional guest name per additional room.
Loyalty programme account number to associate with this booking.
Use this only when the quote has a supported_loyalty_programme indicated. Otherwise, this will result into an error.
Account number is relayed to the hotel on a best-effort basis, it is at the hotel's discretion to honour the loyalty programme.
"201154908"
Lead guest's phone number in E.164 (international) format.
"+442080160509"
Endpoint
POST https://api.duffel.com/stays/bookings
Request
curl -X POST --compressed "https://api.duffel.com/stays/bookings" \-H "Accept-Encoding: gzip" \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Duffel-Version: v2" \-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \-d '{"data": {"users": ["icu_00009htyDGjIfajdNBZRlw"],"quote_id": "quo_0000AS0NZdKjjnnHZmSUbI","phone_number": "+442080160509","payment": {"three_d_secure_session_id": "3ds_0000AWr2XsTRIF1Vp34gh5"},"loyalty_programme_account_number": "201154908","guests": [{"user_id": "icu_00009htyDGjIfajdNBZRlw","given_name": "Amelia","family_name": "Earheart"}],"email": "amelia.earheart@duffel.com","accommodation_special_requests": "2:00 PM early check-in required"}}'
Response
{"data": {"users": ["icu_00009htyDGjIfajdNBZRlw"],"supported_loyalty_programme": "duffel_hotel_group_rewards","status": "confirmed","rooms": 1,"reference": "AFE33SE2","phone_number": "+442080160509","metadata": {"checkout_reference": "usr_0000AePJGl5G9ZYfmNllrs"},"loyalty_programme_account_number": "201154908","id": "bok_0000BTVRuKZTavzrZDJ4cb","guests": [{"user_id": "icu_00009htyDGjIfajdNBZRlw","given_name": "Amelia","family_name": "Earhart"}],"email": "amelia.earheart@duffel.com","confirmed_at": "2023-04-13T15:48:11.642Z","check_out_date": "2023-05-28","check_in_date": "2023-05-24","accommodation": {"supported_loyalty_programme": "duffel_hotel_group_rewards","rooms": [{"rates": [{"total_currency": "GBP","total_amount": "799.00","tax_currency": "GBP","tax_amount": "82.23","supported_loyalty_programme": "duffel_hotel_group_rewards","quantity_available": 12,"public_currency": "GBP","public_amount": "699.99","payment_type": "pay_now","id": "rat_0000BTVRuKZTavzrZDJ4cb","fee_currency": "GBP","fee_amount": "50.94","due_at_accommodation_currency": "GBP","due_at_accommodation_amount": "39.95","deal_types": ["closed_user_group","mobile"],"conditions": [{"title": "Parking","description": "Public parking is available nearby for £15 per day"}],"cancellation_timeline": [{"refund_amount": "799.00","currency": "GBP","before": "2023-05-23T13:00:00Z"}],"board_type": "room_only","base_currency": "GBP","base_amount": "665.83","available_payment_methods": [["balance"]]}],"photos": [{"url": "https://assets.duffel.com/img/stays/image.jpg"}],"name": "Double Suite","beds": [{"type": "king","count": 2}]}],"review_score": 8.8,"rating": 3,"photos": [{"url": "https://assets.duffel.com/img/stays/image.jpg"}],"phone_number": "+442074938181","name": "Duffel Test Hotel","location": {"geographic_coordinates": {"longitude": -0.1416,"latitude": 51.5071},"address": {"region": "England","postal_code": "EC2A 4TP","line_one": "100 Clifton Street","country_code": "GB","city_name": "London"}},"key_collection": {"instructions": "Please collect the keys from accommodation's reception."},"id": "acc_0000AWr2VsUNIF1Vl91xg0","email": "reservations@duffel-hotel-group.com","description": "Ornate quarters, some with grand pianos, in a luxurious hotel offering acclaimed dining & a spa.","check_in_information": {"check_out_before_time": "11:30","check_in_before_time": "00:00","check_in_after_time": "14:30"},"chain": {"name": "Duffel Hotel Group"},"brand": {"name": "Duffel Test","id": "bra_0000Alr8BYNsbmDMThHSbI"},"amenities": [{"type": "parking","description": "Parking"}]}}}