Getting startedPromotions

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

Intro to promotions

The promotions capability of the Lodging Supply GraphQL API enables you to create and manage promotions that offer a percent-based discount on stays for select dates.

Note: You can also download the Promotions launch kit.

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.

Types of promotions

Using this API, you can create these types of promotions:

  • Single promotions, which offer percentage-based discounts (between 1 - 75%) for all nights of a stay (such as 10% off)
  • Day-of-week promotions, which are applicable for specific days of the week within the travel window (such as Mondays at 10%, Tuesdays at 12%, and so on) to help manage occupancy fluctuations
  • Multi-night promotions for extended lengths of stay, where the Nth night can be discounted, so that you can reward travelers who stay longer (such as "Stay 3 nights and get the 3rd night at 40% discount")

Discount tagging

You can attach tags to a promotion for effective merchandising on the points of sale. This discount tagging is available:

  • Basic - Flexible and unrestricted promotions that define a set of qualification criteria, such as booking dates, stay dates, length of stay, and so on. Booking dates can be set to anytime (within a specified window) or to specific days/times (within a specified window).
  • Early booking - Promotions that are relevant to travelers who book in advance. Booking dates can be set to anytime (within a specified window) or to specific days/times (within a specified window). These promotions are merchandized on Expedia brand sites with the relevant early-booking promotion tags, such as “Book Early and Save X% off!”
  • Same day - Promotions that offer last-minute deals for travelers who are checking in on the same day the reservation is made. You can specify the start time in same day this offer can be applied, and you can set a range of dates when the offer should apply. You can also set blackout dates. These promotions are merchandized on Expedia brand sites with the relevant same-day promotion tags, such as “Tonight only Save X% off!”

In addition, you must select these options to set the applicable audience:

  • Member-only deals - Promotions that apply to members only. This type of deal can be offered in addition to an existing offer. (Note that member-only badging is not applied to member-only deals that are less than 10%.)
  • Mobile-only deals - Promotions that apply to travelers who book using a mobile device.

For all promotions, you can specify a minimum and maximum length of stay. And you can create promotions with no end date ("evergreen").

Targeting travelers

How can you use promotions to target valuable travelers? Here are some ideas:

  • If you want to limit promotional pricing to a targeted audience, restrict the length-of-stay or create a mobile-only promotion.
  • To target high-value travelers, create member-only promotions. On average, members book twice as many room nights and spend over two-times that of non-members.
  • To attract highly committed travelers, create early-booking promotions. Committed travelers may be willing to book well in advance of their trips to save money.

Here are examples of how promotions are merchandised on the site:

Single discount:

Same-day discount:

Member-only discount:

Mobile-only discount:

Implementation details

The API offers the following functionality to support promotions:

  • Create a promotion (percent-based discount), as provided by the createSingleDiscountPromotion mutation
  • Create a promotion for specific days of the travel week, as provided by the createDayOfWeekDiscountPromotion mutation
  • Create a multi-night promotion that offers a discount on the Nth night of the stay, as provided by the createMultiNightDiscountPromotion mutation
  • Modify a promotion, as provided by the updateSingleDiscountPromotion, updateDayOfWeekDiscountPromotion, and updateMultiNightDiscountPromotion mutations
  • Query for all promotions that are active on a property, as provided by the property query


  • The promotions capability is not available for large hotel chains due to the complex agreements and bespoke setups of these types of hotels. If you are unsure if hotels in your portfolio are considered large chains, please contact your Technical Relationship Manager.

  • Promotions created using the API cannot be combined (“stacked”).

  • When querying for all promotions, null is returned in these fields. To retrieve data in these fields, query for a specific promotion (by specifying the promotion ID).

    • isMemberOnly
    • isMobileUserOnly
    • blackOutDates
  • Same-day single discount promotions have these limitations:
    • You must create a same-day discount with the SAME_DAY_PROMOTION name; the name cannot be changed after creation. You also cannot update the name of an existing promotion to SAME_DAY_PROMOTION. To change the name from or to SAME_DAY_PROMOTION, you must first deactivate the existing promotion and then recreate it using the desired name.​
    • You cannot include memberOnlyAdditionalValue when creating or updating a SAME_DAY_PROMOTION discount.
    • Travel start and end dates (travelFromDate and travelToDate) cannot be more than 364 days apart.

Minimum certification requirements

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

  • Read all active promotions
  • Create a new promotion (single, day-of-week, and multi-night)
  • Create a new promotion using tags (early booker and same day)
  • Create a promotion for specific audiences (member-only and mobile-only)
  • Modify an existing promotion
  • Delete a promotion

In addition, you must support the following:

  • Transport Layer Security (TLS) 1.2 and HTTPS on your endpoint(s)
  • Obtain credentials to authenticate with our OAuth2 token service