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:

• The ReservationNotificationEvent webhook notification enables us to push real-time notifications to your service endpoint when a reservation is created, modified, or cancelled by a traveler. 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 configuration, which includes its URL, for reservation delivery due to the business impact. Benefits of creating a separate callback URL 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 callback configuration's secret at least 30 days before the expiry date.

  In addition, we recommend specifying an email distribution list 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.

  To create a callback configuration and subscribe to reservation notifications, refer to Notifications.

• The confirmReservationNotification mutation enables you to confirm reservations.

  This mutation requires the confirmation token, which is provided in the webhook notification's payload, and your reservation confirmation code. The confirmation token cannot be retrieved using the reservations query because it is specific to the notification delivery. This ensures that you are 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 or reservation query request retrieves 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 amounts objects to validate the rate and payment impacts that coincide with a reservation update.

Workflow

After notifications and the 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. ReservationNotificationEvent webhook notification is sent to your system, and it includes the Expedia reservation ID and a confirmation token. Here is an example:

   1{ 
   2  "event_name": "ReservationNotificationEvent", 
   3  "creation_time": "2024-10-10T09:49:00.000Z", 
   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} 

3. To acknowledge receipt of the webhook notification, your service endpoint returns the HTTP status code 200. If you do not return status code 200, we continue to resend using the notification using an exponential backoff strategy (the retry interval is increased exponentially after every attempt, for up to 2.5 hours). After a webhook notification expires, the reservation information is sent to the partner via email. Therefore, it is imperative that you send status code 200 upon receipt so that reservation notifications do not fall back to email.

4. Reservation details are then retrieved from our system using the reservations or reservation query. In the following request example, note the filter argument that specifies the reservation ID. For a full example, refer to the reservations 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       ...

   Payment information can also be retrieved 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   ...

5. The reservation is confirmed using the confirmReservationNotification mutation. The confirmation token is the same one sent in the webhook notification. 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} 

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

• The ReservationNotificationEvent webhook notification 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 sent only if the first modification was confirmed).

• If a notification expires and an email message about the reservation is sent instead, all subsequent notifications about that reservation are sent through email. Use the last updated date filter of the reservations query to filter reservations based on the period for which the outage occurred, so that you can recover the impacted reservations.

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

• In-flight reservations 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.

• Null values may be returned in fields of the webhook notification. This is expected, and reservations should not be rejected if null values are returned.

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).