List all bookings

v1.0.0

Returns a list of all the bookings you've made.

You can filter the list based on when bookings were created or last updated, as well as their arrival (start) and departure (end). These date-based filters allow to narrow down the result with modifiers for less than (lt), greater than (gt), lower than or equal to (lte), greater than or equal to (gte) and equal to (eq).

Example: Adding the query parameters start[gt]=2021-05-20&updated[lte]=2020-11-20T11:11:00.000Z would return bookings arriving after May 20th, 2020 that were updated before or on November 20th, 2020 at 11:11 am UTC.

You can specify the sorting order in which bookings are returned:

This is done by using the sortBy query parameter.
Results can be sorted by createdAt and updatedAt
The parameter allows for a comma-separated list of arguments with :asc (ascending, the default if no sorting is specified) and :desc (descending) modifiers.

Input

{
  "type": "object",
  "properties": {
    "created": {
      "type": "object"
    },
    "end": {
      "type": "object"
    },
    "offset": {
      "type": "number",
      "format": "int32"
    },
    "size": {
      "type": "number",
      "format": "int32"
    },
    "sortBy": {
      "type": "string"
    },
    "start": {
      "type": "object"
    },
    "updated": {
      "type": "object"
    }
  },
  "additionalProperties": false
}

Output

{
  "type": "object",
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Details of an existing booking.",
        "required": [
          "bookingId",
          "status",
          "start",
          "end",
          "hotel",
          "bookedRooms",
          "contact",
          "notes",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "bookedRooms": {
            "type": "array",
            "description": "List of rooms booked",
            "items": {
              "type": "object",
              "required": [
                "roomType",
                "rate",
                "notes"
              ],
              "properties": {
                "adults": {
                  "type": "number",
                  "format": "integer",
                  "description": "Number of adult guests booked for this room type."
                },
                "notes": {
                  "type": "object",
                  "description": "Notes about this booked room. These might be requests for room setup (e.g. extra beds or requests to remove alcoholic beverages from the minibar) or other requests related to this particular booked room.\nThese fields allow for **Markdown formatting** that's displayed to hotels in its rendered format in most circumstances but might fall back to text-only in scenarios where that's not possible.",
                  "required": [
                    "fromGuest",
                    "fromSeller"
                  ],
                  "properties": {
                    "fromGuest": {
                      "type": "string",
                      "description": "Notes your guest has entered as part of the booking for this booked room. These allow them to communicate anything noteworthy about this booked room to the hotel, e.g. special instructions around room setup, that the minibar should not contain any alcoholic beverages or a wheelchair-accessible room is required."
                    },
                    "fromSeller": {
                      "type": "string",
                      "description": "Notes from you as a seller allow you to communicate any instructions for this booked room. These are communicated to the hotel as coming from you. You can use this field to provide the hotel with pointers about e.g. room setup, connecting doors that need to be opened, extrabeds to be placed in the rooms or any other instructions."
                    }
                  }
                },
                "rate": {
                  "type": "object",
                  "description": "Information on the price of the booked room, other components of the room (such as breakfast, lunch or a welcome drink) and the cancellation policies that apply.",
                  "required": [
                    "start",
                    "end",
                    "hotelAgreement",
                    "retailRate",
                    "sellerCommissionPercentage",
                    "components",
                    "cancellationPolicies"
                  ],
                  "properties": {
                    "cancellationPolicies": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "A rule that applies if the booking is cancelled.",
                        "required": [
                          "start",
                          "formatted",
                          "fee"
                        ],
                        "properties": {
                          "end": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "fee": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "formatted": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "start": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      }
                    },
                    "components": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "Product or service offered as part of a rate in addition to accommodation in the room.",
                        "required": [
                          "formatted",
                          "type"
                        ],
                        "properties": {
                          "formatted": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "includedInRate": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "type": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      }
                    },
                    "end": {
                      "type": "string",
                      "format": "date"
                    },
                    "hotelAgreement": {
                      "type": "object",
                      "description": "Essential information on an agreement with a hotel.",
                      "required": [
                        "hotelAgreementId",
                        "dealId",
                        "specialInstructions"
                      ],
                      "properties": {
                        "conditions": {
                          "type": "array",
                          "description": "A deal may have conditions set to it. For example, the deal may only apply for a closed user group (PRIVATE_RATE) or sold along with another component e.g flights (PACKAGED)",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        },
                        "dealId": {
                          "type": "string",
                          "description": "The unique identifier for this deal request."
                        },
                        "dealsSellable": {
                          "type": "object",
                          "description": "There is a limit to the number of deals that can be sold. ",
                          "properties": {
                            "remaining": {
                              "type": "object",
                              "additionalProperties": true
                            }
                          }
                        },
                        "discount": {
                          "type": "object",
                          "description": "Rather than selling the hotel's generally available public rates, if a discount is agreed on, bookings made with this deal will have a reduced rate.",
                          "properties": {
                            "count": {
                              "type": "object",
                              "additionalProperties": true
                            },
                            "type": {
                              "type": "object",
                              "additionalProperties": true
                            }
                          }
                        },
                        "hotelAgreementId": {
                          "type": "string",
                          "description": "Unique identifier for the hotel agreement."
                        },
                        "href": {
                          "type": "string",
                          "description": "URI that allows access to the full deal information."
                        },
                        "specialInstructions": {
                          "type": "string",
                          "description": "These are conditions set by you the seller or the hotel for which the deal can be sold. For example: this deal can only be sold on mobile. Any specialInstructions will override other variables, for example, if an instruction includes: All bookings are non refundable, this will override any pre-existing cancellationPolicy."
                        }
                      }
                    },
                    "maxOccupancy": {
                      "type": "number"
                    },
                    "retailRate": {
                      "type": "object",
                      "description": "The public retail rate you should quote and charge your guest. You're not allowed to quote or charge an amount lower than this if your website or app is publicly accessible.",
                      "required": [
                        "total",
                        "taxesAndFees"
                      ],
                      "properties": {
                        "taxesAndFees": {
                          "type": "object",
                          "description": "Breakdown of taxes (e.g. VAT, city tax) and fees (e.g. cleaning or resort fees).",
                          "properties": {
                            "includedInRate": {
                              "type": "object",
                              "additionalProperties": true
                            },
                            "payAtHotel": {
                              "type": "object",
                              "additionalProperties": true
                            }
                          }
                        },
                        "total": {
                          "type": "object",
                          "description": "An amount of money in the specified currency (used in the context of prices, fees, refunds etc.)",
                          "required": [
                            "amount",
                            "currency"
                          ],
                          "properties": {
                            "amount": {
                              "type": "object",
                              "additionalProperties": true
                            },
                            "currency": {
                              "type": "object",
                              "additionalProperties": true
                            }
                          }
                        }
                      }
                    },
                    "sellerCommissionPercentage": {
                      "type": "number",
                      "format": "float",
                      "description": "The commission percentage you as a seller will earn from this booking, based on `retailRate.total`."
                    },
                    "start": {
                      "type": "string",
                      "format": "date"
                    }
                  }
                },
                "roomType": {
                  "type": "object",
                  "description": "Booked room",
                  "required": [
                    "roomTypeId",
                    "name"
                  ],
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "The hotel's name for this room type."
                    },
                    "roomTypeId": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Unique identifier of this room type within the Impala platform."
                    }
                  }
                },
                "sellerToImpalaPayment": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "bookingId": {
            "type": "string",
            "description": "Unique identifier for this booking within the Impala platform."
          },
          "cancellation": {
            "type": "object",
            "description": "Returned in case the booking (or parts of it) has been cancelled. Contains information on the cancellation.",
            "required": [
              "fee"
            ],
            "properties": {
              "fee": {
                "type": "object",
                "additionalProperties": true
              }
            }
          },
          "contact": {
            "type": "object",
            "description": "Guest details for this booking."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Date and time (in UTC and ISO 8601 format) when the booking was created."
          },
          "end": {
            "type": "string",
            "format": "date",
            "description": "The departure date of the booking."
          },
          "hotel": {
            "type": "object",
            "description": "Essential information on a hotel returned as part of other resources, linking to the full resource within its `href` field.",
            "required": [
              "hotelId",
              "name",
              "starRating",
              "images",
              "address",
              "location"
            ],
            "properties": {
              "address": {
                "type": "object",
                "description": "Physical address",
                "required": [
                  "line1",
                  "city",
                  "country",
                  "countryName",
                  "postalCode"
                ],
                "properties": {
                  "city": {
                    "type": "string"
                  },
                  "country": {
                    "type": "string",
                    "description": "Three-character country code in ISO alpha-3 format."
                  },
                  "countryName": {
                    "type": "string",
                    "description": "English name of the country."
                  },
                  "line1": {
                    "type": "string",
                    "description": "First line of the address."
                  },
                  "line2": {
                    "type": "string",
                    "description": "Second line of the address."
                  },
                  "postalCode": {
                    "type": "string"
                  },
                  "region": {
                    "type": "string"
                  }
                }
              },
              "checkIn": {
                "type": "object",
                "description": "A time range. Open-ended time ranges are indicated by omitting either `start` or `end` in the object.",
                "properties": {
                  "from": {
                    "type": "string",
                    "description": "Time in ISO 8601 time format."
                  },
                  "to": {
                    "type": "string",
                    "description": "Time in ISO 8601 time format."
                  }
                }
              },
              "checkOut": {
                "type": "object",
                "additionalProperties": true
              },
              "emails": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "hotelId": {
                "type": "string",
                "format": "uuid",
                "description": "Unique identifier for this hotel within the Impala platform."
              },
              "href": {
                "type": "string",
                "description": "URI that allows access to the full hotel information."
              },
              "images": {
                "type": "array",
                "description": "Photos of the hotel, sorted in the recommended display order (e.g. for photo galleries) starting with the recommended hero image.",
                "items": {
                  "type": "object",
                  "required": [
                    "height",
                    "width",
                    "url"
                  ],
                  "properties": {
                    "altText": {
                      "type": "string",
                      "description": "Alternative text for the image (to be used e.g. to cater to screenreaders)."
                    },
                    "height": {
                      "type": "number",
                      "description": "Height in pixels."
                    },
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "The url of this image. The url of an image might change over time, and we therefore advise not to store or cache image URLs within your app beyond a few minutes."
                    },
                    "width": {
                      "type": "number",
                      "description": "Width in pixels."
                    }
                  }
                }
              },
              "location": {
                "type": "object",
                "description": "Precise location on a map (using WGS 84 longitude and latitude notation)",
                "required": [
                  "latitude",
                  "longitude"
                ],
                "properties": {
                  "latitude": {
                    "type": "number",
                    "description": "WGS 84 latitude."
                  },
                  "longitude": {
                    "type": "number",
                    "description": "WGS 84 longitude."
                  }
                }
              },
              "name": {
                "type": "string",
                "description": "Name of the hotel."
              },
              "phoneNumbers": {
                "type": "array",
                "description": "The hotel's phone number(s)",
                "items": {
                  "type": "string"
                }
              },
              "starRating": {
                "type": "number",
                "format": "double",
                "description": "The star rating (or star-equivalent rating)"
              },
              "timezone": {
                "type": "string",
                "description": "The timezone the hotel is in - e.g AST"
              }
            }
          },
          "hotelConfirmationCode": {
            "type": "string",
            "description": "The hotel's confirmation identifier for this booking."
          },
          "notes": {
            "type": "object",
            "description": "The notes that were transmitted to the hotel as part of this booking.\n\nThese fields allow for **Markdown formatting** that's displayed to hotels in its rendered format in most circumstances but might fall back to text-only in scenarios where that's not possible.",
            "required": [
              "fromGuest",
              "fromSeller"
            ],
            "properties": {
              "fromGuest": {
                "type": "string",
                "description": "Notes your guest has entered as part of the booking. These allow them to communicate anything to the hotel (e.g. that they're travelling for a special occassion or have a particular room assignment preference)."
              },
              "fromSeller": {
                "type": "string",
                "description": "Notes you as a seller want to communicated to the hotel. These might be around operational processes to watch out for. Impala communicates these as coming from you."
              }
            }
          },
          "paymentBearerToken": {
            "type": "string",
            "description": "If status is PAYMENT_REQUIRED, then this should be used as the Authorisation header for the POST to the /payments endpoint."
          },
          "paymentClientSecret": {
            "type": "string",
            "description": "If status is PAYMENT_REQUIRED, then this should be used as the client secret when rendering Impala Payment Elements in the UI."
          },
          "start": {
            "type": "string",
            "format": "date",
            "description": "The arrival date of the booking."
          },
          "status": {
            "type": "string",
            "description": "Status of this booking within the Impala platform. When you make a booking, it'll first appear as `PENDING` until we receive the hotel's confirmation details. At this point your booking will move to `ACCEPTED`.",
            "enum": [
              "CANCELLED",
              "PENDING",
              "ACCEPTED",
              "PAYMENT_REQUIRED",
              "PAYMENT_ABANDONED"
            ]
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Date and time (in UTC and ISO 8601 format) when the booking was last updated."
          }
        }
      }
    },
    "pagination": {
      "type": "object",
      "description": "Information that helps paginate through lists of resources.",
      "required": [
        "count",
        "next",
        "prev",
        "total"
      ],
      "properties": {
        "count": {
          "type": "number",
          "format": "int32",
          "description": "The number of items returned on this page."
        },
        "next": {
          "type": "string",
          "description": "The absolute URL pointing to the next page. Will be null if there are no next pages."
        },
        "prev": {
          "type": "string",
          "description": "The absolute URL pointing to the previous page. Will be null if there are no previous pages."
        },
        "total": {
          "type": "number",
          "format": "int32",
          "description": "The total number of items that exist for your query across all pages."
        }
      }
    }
  }
}