Bookings

A reservation with the stay for the room(s) requested from a quote

accommodation

object

Details of the accommodation reserved for this booking

cancelled_at

datetimenullable

The ISO 8601 datetime of the cancellation of this booking. This is null if the booking is not yet cancelled.

Example: null

check_in_date

date

The ISO 8601 date on which the guest can check in

Example: "2023-05-24"

check_out_date

date

The ISO 8601 date on which the guest needs to check out

Example: "2023-05-28"

confirmed_at

datetime

The ISO 8601 datetime at which the booking was made.

Example: "2023-04-13T15:48:11.642Z"

email

string

Lead guest's email address

Example: "amelia.earheart@duffel.com"

guests

list

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.

string

The id of the booking

Example: "bok_0000BTVRuKZTavzrZDJ4cb"

key_collection

objectnullabledeprecated

The key collection details for the booking. This field is deprecated and will be removed in a future version. Please use Accommodation.check_in_information.key_collection instead.

loyalty_programme_account_number

stringnullable

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.

Example: "201154908"

metadata

objectnullable

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.

Example: {"checkout_reference":"usr_0000AePJGl5G9ZYfmNllrs"}

phone_number

string

Lead guest's phone number in E.164 (international) format.

Example: "+442080160509"

reference

stringnullable

A booking reference for the guest's reservation at the accommodation. This is the reference you should use when contacting the accommodation.

Example: "AFE33SE2"

rooms

number

The number of rooms in the booking.

Example: 1

status

enum

The status of the booking.

Possible values: "confirmed" or "cancelled"

supported_loyalty_programme

enumnullable

The loyalty programme that this booking supports.

Possible values: "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"

users

string[]

The ids of customer users that are allowed to manage the booking.

Example: ["icu_00009htyDGjIfajdNBZRlw"]

Cancel booking

Cancels a specific booking made by your organisation

booking_id

stringrequired

The id of the booking

Example: "bok_0000BTVRuKZTavzrZDJ4cb"

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: v1" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

{
  "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,
              "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",
              "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",
                  "card"
                ]
              ]
            }
          ],
          "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"
      },
      "amenities": [
        {
          "type": "parking",
          "description": "Parking"
        }
      ]
    }
  }
}

Get booking

Gets a specific booking made by your organisation.

stringrequired

The id of the booking

Example: "bok_0000BTVRuKZTavzrZDJ4cb"

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: v1" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

{
  "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,
              "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",
              "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",
                  "card"
                ]
              ]
            }
          ],
          "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"
      },
      "amenities": [
        {
          "type": "parking",
          "description": "Parking"
        }
      ]
    }
  }
}

List bookings

Lists bookings made for your organisation. Returns a list of Duffel Stay Bookings.

after

string

A cursor pointing to the previous page of records. For more information on how to paginate through records, see the Pagination section.

Example: "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="

before

string

A cursor pointing to the next page of records. For more information on how to paginate through records, see the Pagination section.

Example: "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="

limit

integer

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.

Example: 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: v1" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

{
  "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,
                "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",
                "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",
                    "card"
                  ]
                ]
              }
            ],
            "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"
        },
        "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.

accommodation_special_requests

stringnullable

Guest's specific requests about this booking to be forwarded to the accommodation. This field should not be used to provide medical or otherwise sensitive information.

Example: "2:00 PM early check-in required"

email

stringrequired

Lead guest's email address

Example: "amelia.earheart@duffel.com"

guests

listrequired

loyalty_programme_account_number

stringnullable

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.

Example: "201154908"

phone_number

stringrequired

Lead guest's phone number in E.164 (international) format.

Example: "+442080160509"

quote_id

stringrequired

The id of the stay quote you want to book.

Example: "quo_0000AS0NZdKjjnnHZmSUbI"

users

string[]

The ids of customer users that would be allowed to manage the booking.

Example: ["icu_00009htyDGjIfajdNBZRlw"]

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: v1" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
  "data": {
    "users": [
      "icu_00009htyDGjIfajdNBZRlw"
    ],
    "quote_id": "quo_0000AS0NZdKjjnnHZmSUbI",
    "phone_number": "+442080160509",
    "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"
  }
}'

{
  "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,
              "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",
              "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",
                  "card"
                ]
              ]
            }
          ],
          "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"
      },
      "amenities": [
        {
          "type": "parking",
          "description": "Parking"
        }
      ]
    }
  }
}

Bookings

Schema

Cancel booking

URL parameters

Get booking

URL parameters

List bookings

Query parameters

Creating a booking

Body parameters