Intro to reviewsCopy link

The reviews capability is now provided by the Lodging Supply GraphQL API, and it enables lodging partners to manage property reviews. After you integrate this capability, each lodging partner can retrieve approved reviews collected on the Expedia platform after travelers check out. In addition, lodging partners can retrieve an aggregated rating for each review category and respond to reviews.

To support this functionality, the API now offers the following:

• reviews query, which enables partners to retrieve review data including review ID, reservation ID, traveler name, Expedia property ID (EID), review title and body, review creation and update time, traveler ratings, and property manager response
• aggregatedReviews query, which enables you to retrieve aggregated (average) ratings by Expedia brand site and review category
• setReviewResponse mutation, which enables partners to respond to traveler reviews

In addition, a notification service (webhooks) is provided to enable lodging partners to receive real-time notifications when

• Travelers leave a review (GuestReviewSubmitted)
• Traveler reviews are approved (ReviewsApproved)
• Lodging partner responses are approved (ReviewsManagementResponseApproved)
• Lodging partner responses are rejected (ReviewsManagementResponseRejected)

To receive notifications, the partner must subscribe to notification events after you implement them.

All requests must be made over a secure connection. All response bodies, including errors, are encoded in JSON.

Workflow

After the reviews capability and notifications are implemented, the following workflow is possible:

1. Traveler stay ends (checks out).
2. Expedia solicits the traveler to submit a review.
3. Traveler submits a review.
4. GuestReviewSubmitted webhook notification is sent to the lodging partner.
5. If the review is approved, ReviewsApproved notification is sent to the lodging partner. If the review is rejected, steps 2-3 are repeated.
6. Once approved, the review is available via the API and is displayed on the Expedia site.
7. Lodging partner uses the reviews query to retrieve the review and its ID. Lodging partner can also retrieve aggregated ratings for review categories using the aggregatedReviews query.
8. Lodging partner responds to the review using the setReviewResponse mutation.
9. If the response is approved, ReviewsManagementResponseApproved notification is sent to the partner, and the response is displayed on the Expedia site. If the response is rejected, the ReviewsManagementResponseRejected notification is sent.

Implementation details

Be mindful of the following as you implement the reviews query:

• Only approved reviews can be retrieved; reviews that have not been submitted for moderation (pending) and rejected are not returned. Note that reviews may be pending for up to 14 days depending on the lodging partner’s actions and review content.

• Once a stay ends, the traveler has 180 days to review their stay.

• Reviews are not eligible for a management response (isEligibleForResponse: false) under the following conditions:

  • An existing approved management response exists
  • The review was imported by the connectivity partner
  • A management response has been submitted and is in moderation, so it has not yet been approved or rejected
    
    

• Ratings on all Expedia sites are displayed using a 10-point scale, though travelers must submit ratings using a 5-point scale with this integration. For example, a 4 is displayed if a traveler submitted a 2. However, for properties on Hotels.com, ratings are collected through the API using a 10-point scale (no calculation necessary).

• Review data includes details such as review ID, reservation ID, header, review text, score, reviewer name, and reservation dates. Total review count can also be retrieved.

• Reviews can be filtered by ID, review source (imported or platform), Expedia brand (where the property is listed), creation date, update date, and whether the review has a response. Reviews can also be ordered in the response by these factors.

• To receive notifications, your endpoint must use Transport Layer Security (TLS) 1.2 or 1.3, to provide over-the-wire encryption (HTTPS).

When implementing the setReviewResponse mutation, be aware of the following:

• Responses can be submitted for eligible, approved reviews only.

• If a review already has a pending or approved response, then another cannot be submitted for that review. If no response exists or the response was rejected, then a response can be submitted.

Limitations

Be aware of these as you integrate the reviews capability:

• If a lodging partner has a property listed on both Vrbo and Expedia, reviews are retrieved separately for each channel.
• When retrieving reviews, up to 100 reviews can be returned per page.
• To retrieve or update Expedia property reviews, you must specify the Expedia ID.
• When responding to a review using the setReviewResponse mutation, you must specify the property’s Expedia ID (EID).
• Property manager responses are only eligible for platform reviews, if they do not already exist.
• The rate limit is currently set to five transactions per second (TPS).

Minimum certification requirements

To complete certification for the reviews capability, you must prove that your software can perform the following:

• Query reviews by review ID
• Respond to reviews by using the setReviewResponse mutation
• Differentiate between reviews that have and have not been responded to within your software

Retrieving reviews

After you implement the reviews query, lodging partners can retrieve approved property reviews. The query enables partners to retrieve all reviews for a property or retrieve a specific review (based on its ID). In the orderBy object, you can set how to sort the reviews (for example, by creation date) and whether they sorted in ascending or descending order.

By property ID

Here is an example that retrieves all reviews for a property and paginates the reviews, 10 per page (as specified by the pageSize: 10 filter).

• This example retrieves reviews for an Expedia property, therefore the Expedia ID is provided (id: "9309913", idSource: EXPEDIA).

• The query includes the ids object in the payload request, so that both the Expedia ID and supplier ID are returned.

• Reviews are retrieved and sorted by reservation check-in date, from newest to oldest.

The response includes three reviews, which are not eligible for a management response ("isEligibleForResponse": false) because the management responses are approved.

1query { 
2  property(id: "9309913", idSource: EXPEDIA) { 
3    reviews(pageSize: 10) { 
4      totalCount 
5      cursor 
6      reviews { 
7        id 
8        reservation { 
9          reservationIds { 
10            id 
11            idSource 
12          } 
13          status 
14          primaryGuest { 
15            firstName 
16            lastName 
17          } 
18        } 
19        propertyId { 
20          id 
21          idSource 
22        } 
23        status 
24        brandName 
25        source 
26        createdDateTime 
27        lastUpdatedDateTime 
28        title { 
29          value 
30          locale 
31        } 
32        body { 
33          value 
34          locale 
35        } 
36        starRatings { 
37          category 
38          value 
39        } 
40        isEligibleForResponse 
41        response { 
42          status 
43          createdDateTime 
44          lastUpdatedDateTime 
45          body { 
46            value 
47            locale 
48          } 
49        } 
50      } 
51    } 
52  } 
53}

By review ID, review details, or reservation IDs

The reviews query provides the ability to filter reviews by

• Review ID
• Creation date
• Expedia brand (site where the property is listed)
• Update date
• Review source
• Reservation ID
• Whether an owner or property manager response exists

Here are examples of filters:

• By review source and creation date:

  query { 
  property(id: "9309913", idSource: EXPEDIA) { 
    reviews( 
      pageSize: 10,  
      filter: { 
        source: "PLATFORM", 
        createdDate: {from: "2022-01-30", to: "2022-01-31"} 
      } 
    ) { 
    … 
  

• By reservation ID:

  query { 
  property(id: "9309913", idSource: EXPEDIA) { 
    reviews( 
      pageSize: 10,  
      filter: { 
        reservation: { 
          reservationIds: { 
            id: "1401556215",  
            idSource: EXPEDIA 
          } 
        } 
      ) { 
    … 
  

• By brand (site where the property is listed):

  query { 
  property(id: "9309913", idSource: EXPEDIA) { 
    reviews( 
      pageSize: 10,  
      filter: { 
        brandNames: [EXPEDIA] 
        } 
      ) { 
    … 
  

The following full example retrieves a property’s reviews and then filters the results by a specific review ID. In the response, note that the review is not eligible for a management response ("isEligibleForResponse": false) because the management response has not been submitted for moderation.

1query { 
2  property(id: "9309913", idSource: EXPEDIA) { 
3    reviews(pageSize: 10, filter:{reviewId: "61f87508de53060cb1ff59e9"}) { 
4      totalCount 
5      cursor 
6      reviews { 
7        id 
8        reservation { 
9          reservationIds { 
10            id 
11            idSource 
12          } 
13          status 
14          primaryGuest { 
15            firstName 
16            lastName 
17          } 
18        } 
19        propertyId { 
20          id 
21          idSource 
22        } 
23        status 
24        brandName 
25        source 
26        createdDateTime 
27        lastUpdatedDateTime 
28        title { 
29          value 
30          locale 
31        } 
32        body { 
33          value 
34          locale 
35        } 
36        starRatings { 
37          category 
38          value 
39        } 
40        isEligibleForResponse 
41        response { 
42          status 
43          createdDateTime 
44          lastUpdatedDateTime 
45          body { 
46            value 
47            locale 
48          } 
49        } 
50      } 
51    } 
52  } 
53}

Retrieving aggregated ratings

Use the aggregatedReviews query to retrieve an average rating for each review category available on Expedia brand sites. Here is an example that retrieves aggregated ratings for reviews collected on Expedia and Orbitz:

1query { 
2  property(id: "9309913", idSource: EXPEDIA) { 
3    aggregatedReviews(filters: {brandNames: [EXPEDIA, ORBITZ]}) 
4    {
5      brandsWithScores {
6        brandName
7        categoriesWithScore {
8          category
9          value {
10            reviewsCount
11            score
12          }
13        }
14        totalReviewsCount
15      }
16    }
17  }
18}

Responding to reviews

Use this mutation to respond to a traveler review.

1mutation { 
2  setReviewResponse(  
3    propertyId: "9309913", 
4    propertyIdSource: EXPEDIA, 
5    reviewId: "61f87508de53060cb1ff59e9", 
6    body: { 
7      value: "Thank you very much for the generous review.",  
8      locale: "en-US" 
9    } 
10  ) { 
11    createdDateTime 
12    status 
13    body { 
14      value 
15      locale 
16    } 
17  } 
18}