Getting startedReservations

Prerequisite: Availability and Rates API | Booking Notification or Booking Retrieval API

Intro to reservations

Note: Before implementing reservation retrieval or update, contact your Technical Relationship Manager to discuss upcoming enhancements to the API that might impact your development efforts.

The reservations capability of the Lodging Supply GraphQL API enables a partner to retrieve reservations made on an Expedia Group point-of-sale. It also enables lodging partners to update reservations in their system based on changes in our system.

Note: You can download the launch kit here.

After you have integrated this capability, please share your feedback here. Your feedback is valuable to us and will be shared directly with the Product teams responsible for delivering new API features and functionality.

Reservation retrieval

The reservations query is provided to enable a partner to retrieve reservations made on an Expedia Group point-of-sale. Once the query is implemented, lodging partners can use this capability to

  • Filter reservations by checkout date to export in-flight reservations when onboarding a new property to their connected software solution.
  • Filter reservations by last updated date to backload reservation data for reservation events that were impacted by connection outage to our reservation delivery APIs (Booking Retrieval and Booking Notification).
  • Filter by reservation IDs to pinpoint specific reservations and associated details, if a partner need to verify perks, accessibility request, and loyalty status prior to arrival.
Note: This capability retrieves reservations for properties that were onboarded to Expedia sites only. Retrieving reservations for Vrbo properties is not supported at this time.

Limitations

Be aware of these limitations when implementing the reservation retrieval feature of the reservations capability:

  • The reservations retrieval capability is read-only and returns a summary of each reservation. Write operations are not supported at this time.​

  • The following data points are not currently retrieved: credit card information, compensation, and per-stay and per-person fees.

  • Only reservations for local inventory are retrieved.​

  • The state of a failed reservation cannot be changed once retrieved. If a reservation failed to be delivered by the Booking Notification or Booking Retrieval API, this capability enables you to retrieve these reservations, though modifications or cancellations to those reservations will be delivered using the secondary delivery method, such as email or fax.​

  • You can query for reservations based on checkout dates, reservation ID, and dates when reservations were last updated. You cannot query for reservations based on booking dates.

  • Up to 10,000 reservations can be retrieved using this capability.

Minimum certification requirements

To adopt the reservation retrieval feature, you must successfully complete end-to-end certification with Expedia Group teams.

  • You are expected to retrieve reservations by all filters: checkout date, last updated date and time, and reservation IDs.

  • The following information must be surfaced in your user interface, saved, and passed to your property management system (PMS). Examples will be requested during certification.

    • Perks / Value add promotions
    • Accessibility request
    • Loyalty status
  • You must be able to support the reconciliationEligibility object if adopting the reservation update feature.

Reservation update

The reservations capability enables lodging partners to update reservations on or before a reservation’s check-in date. After the cancelReservation mutation is implemented, the following actions are available to partners:

  • Cancel a reservation as requested by the guest
    A lodging partner can request to cancel a reservation and agree to waive (or refund, if applicable) any cancellation fees and other amounts associated with the reservation. Expedia Group will not charge any compensation for these waived amounts.

  • Cancel a reservation if the method of payment is invalid (Hotel Collect only) If the credit card provided by the traveler is invalid, the partner can request to cancel the reservation and agree to waive (or refund, if applicable) any cancellation fees and other amounts associated with the reservation. Expedia Group will not charge any compensation for these waived amounts.

In addition, the reservations capability enables lodging partners to reconcile reservations on or after a reservation’s check-in date as follows:

  • Cancel a reservation if the guest does not show up or if requested by the guest After the cancelReservationReconciliation mutation is implemented, a partner can specify the penalty amount that the guest was charged and ensure that Expedia Group will charge a commission on the penalty amount that the guest was charged instead of the original amount.

  • Update a reservation if the travel dates or daily rates applied to the reservation were modified After the changeReservationReconciliation mutation is implemented, the partner can communicate updated stay dates or rates to Expedia Group so that we charge commission on the amount that was charged to the guest.

If you intend to implement the reservation update feature, you must implement reservation retrieval, which enables lodging partners to determine whether reservations are eligible for reconciliation. Partners will not need to rely on error messaging or hard-coded reconciliation criteria in their systems. Instead, they can proactively query for eligibility criteria so that they know exactly which reconciliation actions can be taken.

To determine if a reservation is eligible for updates, include the reconciliationEligibility object in the reservations query, as documented here.

Note: After a reservation is updated, notifications are not sent through any of the booking APIs (Booking Notification, Booking Confirmation, Booking Retrieval), if they are used to maintain inventory. Similarly, no changes are made to inventory to reflect the update.

Limitations

Be aware of these limitation when implementing the reservation update feature:

  • Reconciliation (on or after a reservation’s check-in date) can be performed on Hotel Collect reservations for independently managed properties operating under the Hotel Collect or Expedia Traveler Preference business model. This capability is not available for Hotel Collect Group Reconciliation properties.

  • Updates (before a reservation’s check-in date) can be performed on Expedia Collect and Hotel Collect reservations.

  • Only Expedia IDs (property and reservation IDs) are allowed as arguments.

  • Reservations can be reconciled up to three times when modifying a reservation and only once when cancelling a reservation. (However, partners cannot reset a cancellation using the API; they must use Partner Central to do so).

Minimum certification requirements

To adopt the reservation update feature, you must successfully complete end-to-end certification with Expedia Group teams. You are expected to confirm reservation update eligibility by retrieving reservations using the reservation retrieval feature (by reservation ID, checkout date, or last updated date and time) and the reconciliationEligibility object.

For pre-arrival cancellation, you must be able to perform following actions:

  • Cancel a reservation if the method of payment is invalid (Hotel Collect).
  • Cancel a reservation as requested by the guest (Hotel Collect and Expedia Collect).

For reconciliation after the guest arrives, you must be able to perform following actions:

  • Cancel a reservation as requested by the guest. In the event of no-show, you must be able to cancel a reservation after the check-in date.
  • Update a reservation's stay dates and amounts after the check-in date.
  • Inform Expedia Group of the final reservation status regardless of any financial implication, even when the reservation is non-refundable.

Comparison to booking APIs

If you have coded to the Booking Notification or Booking Retrieval API, be aware of these differences in the response attributes of this API:

Booking APIsReservations capability
Prefix the value of the rate ID in the source field with an "A-" to indicate that a reservation is Hotel Collect, such as A-Expedia or A-Hotels.comRemoves the prefix from the rate ID and provides the businessModel field so that partners can identify the collection model
Offer three types of transactions: original reservation, modified reservation, and cancelled reservation​Provides the status field, which currently only supports BOOKED and CANCELLED values
Bed types, smoking preference, multi-room reservation messages, and payment instructions are represented within SpecialRequests with unique request codes​Provides the bedTypes, smokingType, and multiRoomText fields, and the specialRequest field returns the traveler-specific requests for reservations​
Return the total amounts after tax along with the tax amountReturns the total amount after tax and the total amount before tax (a difference between the two indicates the tax amount)

In addition, the Lodging Supply GraphL API returns Unicode characters if the guest provided these in the reservation. This includes non-ASCII characters and non-English characters such as Chinese and Japanese, which could be included in guest names and special requests. Therefore, you must support all UTF-8 and Unicode characters.