Create a booking

v1.0.0

Creates a booking for for the rate and dates you specify in the request body.

You'll need a roomTypes[].rates[].rateId that's bookable for those dates, which you can find using the endpoint.

If you have provided a credit card on the dashboard then Impala will send the booking to the hotel immediately. We'll ensure payment is taken care of before your guest arrives at the hotel.

Your guest needs to be paying you the rate specified in retailRate (as listed in the response) before you submit this request.
Once your request is received and the booking is confirmed, Impala will charge you as the seller this retailRate minus the sellerCommissionPercentage (which is the affiliate commission you get to keep). We'll use the business credit card you've added to your account as payment method for this.
The difference between the amount you charge your guest (retailRate, e.g. 200 €) and what Impala charges you (retailRate minus sellerCommissionPercentage, e.g. 200 €) is your commission (in this example: 20 €) to keep.

You can find more information on how money flows between your guest and you, and you and Impala,

This request might take up to 20 seconds to load. While we work to return a response to your request within milliseconds in most cases, some bookings require us to re-verify current pricing in real-time and doing so might take up to 20 seconds. Please make sure your app handles this waiting state appropriately.

Input

{
  "type": "object",
  "required": [
    "bookingContact",
    "end",
    "rooms",
    "start"
  ],
  "properties": {
    "bookingContact": {
      "description": "Details of your guest (will be provided to the hotel in case of questions).",
      "type": "object"
    },
    "end": {
      "type": "string",
      "format": "date",
      "description": "The last day of the desired stay range in ISO 8601 format YYYY-MM-DD."
    },
    "notes": {
      "type": "object",
      "description": "Notes allow sellers to their guests to communicate relevant information to the hotel.",
      "properties": {
        "fromGuest": {
          "type": "string",
          "description": "Notes a guest has entered as they made the book can be added here. This allows you to display a free text field to your guests where they can enter any information they want to communicate to the hotel (e.g. that their booking is for a special occassion or that they have a particular room preference)."
        },
        "fromSeller": {
          "type": "string",
          "description": "Notes you as a seller want to communicate to the hotel. You might use this field to communicate operational processes to watch out for (e.g. providing the hotel with context around where the booking was made or what to watch out for) or information about the guest."
        }
      }
    },
    "paymentType": {
      "type": "string",
      "description": "How will the guest make payment for this booking?",
      "enum": [
        "API"
      ]
    },
    "rooms": {
      "type": "array",
      "description": "List of room type identifiers to be booked.",
      "items": {
        "type": "object",
        "required": [
          "rateId",
          "adults"
        ],
        "properties": {
          "adults": {
            "type": "number",
            "description": "The number of adult guests staying in the room."
          },
          "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."
              }
            }
          },
          "rateId": {
            "type": "string",
            "description": "The unique identifier of this rate within Impala. Every rate returned in the `roomTypes[].rates[]` array when retrieving hotel availability includes this id."
          }
        }
      }
    },
    "start": {
      "type": "string",
      "format": "date",
      "description": "The first day of the desired stay range in ISO 8601 format YYYY-MM-DD."
    }
  }
}

Output

{
  "type": "object",
  "description": "Details of an existing booking.",
  "required": [
    "bookedRooms",
    "bookingId",
    "contact",
    "createdAt",
    "end",
    "hotel",
    "notes",
    "start",
    "status",
    "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": "string",
                      "description": "The time (in the hotel's local timezone) at which the policy takes effect, in ISO 8601 format. If omitted, the policy applies open-ended until the guests' stay."
                    },
                    "fee": {
                      "type": "object",
                      "description": "Describes the costs associated with a cancellation and how it is calculated.",
                      "required": [
                        "type",
                        "price"
                      ],
                      "properties": {
                        "count": {
                          "type": "number",
                          "description": "The value that is used in calculation of the cost. This could be 50 in case of a 50% fee being charged for a type \"PERCENTAGE\" or 2 in case of the initial two nights of the stay being charged in full as a fee if the type is \"NIGHTS\"."
                        },
                        "price": {
                          "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
                            }
                          }
                        },
                        "type": {
                          "type": "string",
                          "description": "The way in which the cancellation fee is calculated. This can be \"NONE\" in case a full refund is paid out, \"NON_REFUNDABLE\" if no refund is paid out and the full amount is due, \"PERCENTAGE\" if a percentage of the total price for the stay is charged as cancellation fee, \"NIGHTS\" if a defined number of initial nights of the stay are charged in full as cancellation fee or \"FLAT\" in case a flat cancellation fee is charged.",
                          "enum": [
                            "NON_REFUNDABLE",
                            "PERCENTAGE",
                            "NONE",
                            "NIGHTS",
                            "FLAT"
                          ]
                        }
                      }
                    },
                    "formatted": {
                      "type": "string",
                      "description": "Human-readable plain English cancellation policy information, ready to be shown to your guests."
                    },
                    "start": {
                      "type": "string",
                      "description": "The time (in the hotel's local timezone) at which the policy takes effect, in ISO 8601 format. If omitted, the policy is already in effect."
                    }
                  }
                }
              },
              "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": "string",
                      "description": "Human-readable plain English version of the component included in the rate, ready to be shown to your guests."
                    },
                    "includedInRate": {
                      "type": "boolean"
                    },
                    "type": {
                      "type": "string",
                      "description": "The type of product or service included in the price. We currently support rates including \"BREAKFAST\", \"LUNCH\", \"DINNER\" and \"ALL_INCLUSIVE\".",
                      "enum": [
                        "BREAKFAST",
                        "LUNCH",
                        "DINNER",
                        "WELCOME_BEVERAGE",
                        "ALL_INCLUSIVE"
                      ]
                    }
                  }
                }
              },
              "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": "string"
                    }
                  },
                  "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": "number",
                        "description": "The amount of deals remaining that can sold."
                      }
                    }
                  },
                  "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": "number",
                        "description": "This is the amount of discount received."
                      },
                      "type": {
                        "type": "string",
                        "description": "This is the type of discount which can be: PERCENTAGE or FLAT_FEE."
                      }
                    }
                  },
                  "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": "array",
                        "description": "Taxes and fees that are included in the `retailRate.total` price paid at the time of booking.",
                        "items": {
                          "type": "object",
                          "description": "Details of a tax or fee (included or excluded in a rate).",
                          "properties": {
                            "category": {
                              "type": "object",
                              "additionalProperties": true
                            },
                            "charges": {
                              "type": "object",
                              "additionalProperties": true
                            },
                            "formatted": {
                              "type": "object",
                              "additionalProperties": true
                            }
                          }
                        }
                      },
                      "payAtHotel": {
                        "type": "array",
                        "description": "Taxes and fees that need to be payed at the hotel (often upon arrival or departure). This frequently happens for fees that only need to be collected based on certain conditions (e.g. a guest coming from abroad or being older than a certain age).",
                        "items": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      }
                    }
                  },
                  "total": {
                    "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": [
        "address",
        "hotelId",
        "images",
        "location",
        "name",
        "starRating"
      ],
      "properties": {
        "address": {
          "type": "object",
          "description": "Physical address",
          "required": [
            "city",
            "country",
            "countryName",
            "line1",
            "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."
    }
  }
}