Getting startedPromotions

Prerequisite: Availability and Rates API | Booking 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 Provider Handbook and Developer Guide.

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, travel 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 can select the applicable audience using these options:

  • Member-only deals - Promotions that apply to members only. This type of deal can be offered in addition to an existing offer.
  • 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.

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:


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

Guidelines to follow when using promotions:

  • Do not mislead travelers in any way when creating promotions for display on our websites that offer discounts on your standard rates. Do not offer discounts that are based on false information.
  • Ensure that all promotions provided for display on our websites are actually given to guests who have made promotional bookings. For example, if you upload a discounted price for booking, you must honor that price.
  • If you create a time-limited discount, such as a 72-hour sale, the discounted price for that particular property/room/room type must only be available for the duration of that promotion. After the time period, the price should return to your regular (non-discounted) price for a reasonable period of time.
  • You are responsible for understanding the laws applicable to your promotions and ensuring that your promotions and other content comply with all applicable laws. These guidelines are not legal advice. Expedia Group reserves the right to remove any promotions that we believe are in violation of these guidelines or applicable law.


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 Connectivity Account Manager.

When querying for all promotions, null is returned in these fields:

  • isMemberOnly
  • isMobileUserOnly
  • blackOutDates

To retrieve data in these fields, query for a specific promotion (by specifying the promotion ID).

Same-day single discount promotions limitations:

  • You must create a same-day discount 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 with SAME_DAY_PROMOTION.