API introCopy link

The Lodging Supply GraphQL API enables Expedia connectivity providers to retrieve property information, reservation data, regulatory information, and more. This is a GraphQL API, and all request and response bodies, including errors, are encoded in JSON. All requests and responses must be made over a secure connection.

Endpoint

https://api.expediagroup.com/supply/lodging/graphql

All requests must be made over a secure connection. All response bodies, including errors, are encoded in JSON. If no response is returned within 65 seconds, the request has timed out; set your retry logic accordingly.

Use the POST method as shown in this syntax statement:

curl --request POST \
     --url https://api.expediagroup.com/supply/lodging/graphql \
     --header 'Authorization: Bearer {token}' \
     --header 'Content-Type: application/json' \
     -d ' {
      property(id: "{id}")
        ...
      }
     '

Even though a POST is sent to the GraphQL endpoint, data will only be retrieved, not modified, because the body contains queries only.

Authentication and authorization

This API uses OAuth2 for delegating access to resources. Rather than passing username/password credentials with each request, you can periodically obtain an access token from the OAuth2 server to send within API requests in the form of a bearer token header. The token is used to authenticate and authorize access to the specified property.

If you issue a request using an expired token, an error is returned stating that the token is invalid. We recommended that you retrieve a new token several seconds before it expires to avoid any service disruption. (The expires_in attribute in the response indicates the number of seconds a token is valid.)

If you are calling the API from multiple servers, you can request a unique access token from each server and save it in memory. It is not necessary to persist the token to disk and attempt to reuse across all servers in your application. This should simplify your solution and is potentially more secure as the token is less likely to be compromised if it is not persisted to disk.

Obtaining an access token

To obtain an access token, complete these steps:

1. Obtain API credentials, which will be used to authenticate with the OAuth2 token service:

   • If you are an existing API partner, use your current API credentials to fetch the access token. You would usually use these credentials to access other APIs, such as Availability and Rates, Property, and Product. They are typically prefixed with ”EQC”.

     Note: If your password contains less than 16 characters, you must change your password. Passwords must contain at least 16 characters and include at least three of the following: uppercase letter, lowercase letter, a number, and a symbol. Passwords cannot contain these symbols: <, >, &, %, +, ', and "

   • If you are new partner, obtain Expedia credentials by submitting your request on this page.
     
     

   Ensure that these credentials are stored securely and are not exposed to your users through cookies, web storage, browser or mobile applications, and so on.

   Note: If you onboarded properties directly to Vrbo in addition to Expedia, you must obtain a separate token using your Vrbo credentials to use the API to issue requests based on Vrbo supplier IDs. The Expedia token can only be used to issue requests based on Expedia IDs.

2. Encode the username and password to Base64 by following the OAuth2 standard requirements.

3. Send a request to the OAuth2 token service (https://api.expediagroup.com/identity/oauth2/v3/token). The Content-Type header is required, and grant_type must be specified as a separate data parameter (shown below) or it must be included in the URL.

   Note that the access token's length may vary and additional attributes will be present in the response. Also, the expires_in attribute indicates how long the token is valid (in seconds). This value will change, so be sure to obtain the actual value of the field returned to you and use it to determine the expiration status of your token (and dynamically refresh the token based on expires_in).

4. Save the access token in a secure fashion (preferably in-memory), and do not expose the token to your users in any way. Do not attempt to parse the contents of the access token because they are subject to change. Always send the token directly to the API over a secure TLS connection using server-to-server communications.

Here is an example request to obtain a token:

curl -i -X POST https://api.expediagroup.com/identity/oauth2/v3/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic {base64_encoded_credentials}" \
  -d "grant_type=client_credentials"

Example response:

{
  "access_token": "oVapAccHHYCGzggNaVHP.ys7dffRkOP2om9Hkbylo.tssKms0UIo9KScLlegv1",
  "token_type": "bearer",
  "expires_in": 1799, 
  "scope": "lodging-supply.property-status.get"
}

Calling the API with an access token

After you obtain an access token, you must include it with all API requests; every request must be authenticated, no anonymous access is allowed. Pass the token in the header of requests as follows:

Authorization: Bearer {token}

If you have a valid token, your request is processed by the API. Otherwise, an error is generated indicating that the token has expired or is invalid in some way.

HTTP headers

Here are the request and response headers for calls made to the Lodging Supply GraphQL API.

Request headers

Response headers

Because the API is used over HTTP, standard headers that are part of the HTTP specification and industry standard extensions are returned as part of the response. However, be aware of the transaction-id response header, which provides a unique transaction ID generated by Expedia Group for all responses. Expedia Group recommends storing this identifier because it can be used to reference responses when troubleshooting GraphQL issues with Expedia Group.

Rate limits

A rate limit is the number of requests received by the API within any given second. We ask each partner to issue no more than five requests per second. We constantly evaluate traffic as it surges and subsides. We will adjust the limit as needed to protect the our platform, partners, and travelers. If you receive the HTTP 200 status code with the RATE_LIMIT_EXCEEDED error code, you have exceeded our rate limit and should consider throttling your requests.

Testing requests and responses

We provide a graphical integrated development environment (IDE) that enables you to issue query requests using test data. This GraphQL explorer is available on many doc pages on this site. Or, you can install a third-party IDE (desktop app), such as Prisma or Insomnia. After you install the application, configure it with either your client ID and secret or a token generated using these values. Refer to the application's documentation for more information about configuring authorization and headers. Then, load our GraphQL endpoint URL and issue test requests as needed.

Error handling

An error can occur during different phases of a GraphQL request (authentication, validation, schema generation, and execution). If an error occurs, an HTTP status code is returned as well as an error object. The HTTP status code of 200 is returned if a GraphQL execution error occurs, and a non-200 status code is returned if an HTTP or GraphQL request error occurs. For a list of HTTP status codes and GraphQL error classes, refer to Error handling.