Reservation deliveryCopy link

Reservation delivery facilitates reservation fulfillment, and it ensures that connected partner systems are notified of reservation events in real time while also maintaining the flexibility that GraphQL’s query-based approach provides. Reservation delivery provides the following:

• A webhook notification (from our system to the partner’s) that enables us to push real-time notifications to your service endpoint when a reservation is created, modified, or cancelled by a traveler (ReservationNotificationEvent event type). Events are sent to your endpoint using the HTTPS protocol as a JSON payload. You can then use these notifications to execute actions in your system.

  We recommend that you use a unique callback URL for reservation delivery due to the business impact. Benefits of creating a separate callback URL for reservation events include the ability to prioritize incoming reservation traffic, avoid overloading a single endpoint, quicker and more targeted troubleshooting, and the ability to monitor the reservation callback configuration’s secret expiry and act accordingly. We recommend that you renew the secret at least 30 days before the expiry date.

  In addition, we recommend specifying an email distribution list to use for the contact email address on the callback configuration. This is because individual email addresses can become obsolete, which increases the risk of expiry secrets not being reset in time.

• The confirmReservationNotification mutation (from the partner’s system to ours) that enables partners to confirm receipt of the notification.

  To confirm a reservation, the confirmation token and reservation confirmation code are required. These are provided in the notification payload; they cannot be retrieved using the reservations query) as they are specific to the notification delivery. This ensures that the partner is confirming the latest reservation information on the reservation. The reservation ID is the same across transactions (booking, modify and cancel), but the confirmation token and reservation confirmation code are tied to the transaction.

• A reservations query request (from the partner’s system to ours) to retrieve the reservation object and targeted attributes. This way, the most current and accurate data is reflected in the connected system. It is very important that the query includes the Payment and ReservationAmount objects to validate the rate and payment impacts that coincide with a reservation update.

Migrating from booking APIs

Adopting reservation delivery alongside other feature enhancements enables partners to migrate from the Booking Retrieval and Booking Confirmation APIs and leverage GraphQL for all reservation fulfillment and management needs. (As GraphQL has become Expedia Group’s standard for supply APIs, Booking Retrieval and Booking Notification APIs are now in a state of maintenance and will not take on further feature enhancements.)

Adopting reservation delivery and completing the migration process unlocks the following:

• Sunsetting of your Booking Retrieval and Booking Confirmation API integrations
• Alignment with the new, common Expedia Group API webhook framework
• Unification of the GraphQL reservation API tech stack
• Streamlined access to the most recent and relevant GraphQL feature launches

As we continue to design and build enhancements for our GraphQL API to assist streamlining workflows and accommodating our partners’ goals, we would love to hear your thoughts and feedback directly for how we can best align our solutions to meet your organization's needs. Please share feedback here.

Implementation details and limitations

• A notification for a reservation event is sent only if the previous transaction for the same reservation was confirmed. For example, a notification is sent for a cancellation only if the reservation itself was confirmed. Similarly, if there were three modifications on a reservation, a notification is sent for the third modification only if the second modification was confirmed (and the second is this sent only if the first modification was confirmed).

• Modifications and cancellations made through the reservation management capability after a traveler’s arrival will not trigger notifications (event types MODIFIED/CANCELLED).

• In-flight bookings that were delivered through the Booking Retrieval or Booking Notification API but not confirmed through the API will not trigger future event notifications through reservation delivery.

• If a reservation is created and a webhooks notification is sent, the reservation can be retrieved using the reservations query and confirmed using the confirmReservationNotification mutation.

Workflow

After notifications and the new mutation are implemented, here is how they fit into the reservations workflow:

1. Traveler reserves a room, updates a reservation, or cancels a reservation.

2. Webhook notification (ReservationNotificationEvent) is sent to the lodging partner, which includes the reservation ID and a confirmation token. Here is an example:

   1{ 
   2  "event_name": "ReservationNotificationEvent", 
   3  "creation_time": "2024-10-10T09:49:08.297506452Z", 
   4  "notification_id": "e85b23f3-5d13-412a-8a63-9a974373d0899", 
   5  "payload": { 
   6    "property_id": "64250", 
   7    "reservation_id": "790320252", 
   8    "confirmation_token": "NTk3NzOD66869k=", 
   9    "action_type": "BOOKED", 
   10    "property_source": "EXPEDIA_GROUP" 
   11  } 
   12} 

   In the event that there are issues receiving a webhook notification (because of a database failure, network outage, unavailable callback URL, and so on), we attempt to resend the notification using an exponential backoff strategy where the retry interval is increased exponentially after every attempt, for up to 2.5 hours. After a webhook notification expires, a notification is sent to the partner via email.

3. The lodging partner retrieves the reservation using the reservations query; note the filter argument. Here is a request excerpt. For a full example, refer to the query reference.

   1query { 
   2  property(id: "64250", idSource: EXPEDIA) { 
   3   reservations( 
   4     filter: { 
   5       reservationIds: [ 
   6         { 
   7           id: "790320252", 
   8           idSource: "EXPEDIA" 
   9         } 
   10      ] 
   11   ) { 
   12     totalCount 
   13     pageInfo { 
   14       hasNextPage 
   15       endCursor 
   16     } 
   17     edges { 
   18       node { 
   19         reservationIds { 
   20           id 
   21           idSource 
   22         } 
   23         reconciliationEligibility { 
   24           validScenarios 
   25           invalidScenarios { 
   26             scenario 
   27             reason 
   28           } 
   29         } 
   30       isReconciled 
   31       ...

   Partner can also retrieve payment information using the paymentInstrument query (if a token was retrieved by the reservations query). Here is a request example:

   1query { 
   2  paymentInstrument(token: "xMNne7tnf0jF3C9qkIC45r4Q0NFz-o7bV8PnZKeRs:Mmn0KoTQCHtNOY4XLgw4Pi") { 
   3   number
   4   expirationDate
   5   activationDate
   6   ...

4. The partner confirms the notification and sends the reservation confirmation number using the confirmReservationNotification mutation. Here is an example:

   1mutation { 
   2  confirmReservationNotification( 
   3    input: { 
   4      clientMutationId: "liaj8a500ad", 
   5      propertyId: "64250", 
   6      reservationId: "790320252", 
   7      confirmationToken: "NTk3Nz55s5sg5ODk=", 
   8      confirmationCode: "59aoi9alje", 
   9      actionType: "BOOKED" 
   10    } 
   11  ) { 
   12    clientMutationId 
   13    reservation { 
   14      id 
   15    } 
   16  } 
   17} 

Minimum certification requirements

To adopt the reservation delivery feature, you must successfully complete end-to-end certification with Expedia Group teams. You must demonstrate that you can support the following:

• Webhook notifications, including the use of a unique callback URL for reservation delivery due to the business impact of reservations
• Reservation retrieval by reservation ID
• Reservation confirmation

In addition, you must also display error messages in your user interface (UI).