Change a booking

v1.0.0

Updates the specified booking with immediate effect. This action might result in a cancellation charge being charged.

Please note that if you wish to change the contact details associated with a booking, you should use the endpoint.

Changes / updates a confirmed booking with the details you provide in the request body.

When your guest needs to change their booking, you can use this endpoint to change any of the details you initially supplied when you , e.g. you'll need to query for availability and use the roomTypes[].rates[].rateId that are available currently for their new stay dates. Any new rates selected must be for the same hotel as the original booking.

A booking cannot be updated on or after the check in day of the original or new stay.

In addition, we require you do supply a updateBookingVersionAtTimestamp field with the updatedAt timestamp of the booking. You can find this value by looking up the booking via the endpoint. This is to avoid race conditions where another update might have happened since the last time you have checked for the current details of this booking.

The status of this booking will switch back to PENDING until we have submitted and confirmed the new details with the hotel.

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"
}

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."
    }
  }
}