Retrieves information about a single property's promotions. You can retrieve all active promotions for a property, or you can retrieve a single promotion. Promotions include single, day-of-week, and multi-night discounts. Each promotion has an assigned promotion ID that can be used for subsequent management.
Information is returned at the property level, not the unit level.
Note: The promotions query is nested under the property query, which provides access to other capabilities, such as property status and reservations. However, you must be granted access to each capability before you can code to it. Contact your Technical Relationship Manager if you are interested in more than promotions.
Use the interactive GraphQL explorer in the following sections to run a sample query. A test property ID is passed into the explorer; its test data is returned. The GraphQL explorer will help you get comfortable with the GraphQL:
For each query, a test property ID is passed into the explorer; its test data is returned.
Click Run Query to execute the query in the explorer on the page. You can modify the query to retrieve the desired fields, and the explorer provides a list of fields when you start typing.
Click API Explorer to launch the full explorer in another tab/window, which provides syntax highlighting, schema introspection, real-time error highlighting, and auto-completion, among other things.
For an Expedia property, specify the Expedia ID (EID) of the property.
For a Vrbo property, specify the ID in this format:
systemId/advertiserId/listingExternalId. For direct PM integrations, the
value of systemId is “PM”. For PMS integrations, this value represents the
PMS originating the request. If you are unsure of your system ID, contact
your Engagement Manager or Technical Relationship Manager.
Source system. For an Expedia property, specify EXPEDIA. For a Vrbo
property, specify SUPPLIER; do not specify VRBO because the specified ID is
the external ID in the partner's system.
Compliance status according to the local jurisdiction's regulatory requirements.
This object returns a non-compliant status for mandatory requirements only. If
invalid information is provided for an optional regulatory requirement, or if
regulatory information is set in a jurisdiction that does not require regulatory
information, status: COMPLIANT will be returned. However, for optional
requirements, a warning is returned in the warningStatus field when the data
is set (using the updateUnitRegistration mutation).
Field
Description
reason
Not nullable.
Reason why the unit is in or out of compliance. The label used for the
registration number in this string comes from the numberTypeLabel field on
the RegistrationNumberRequirement type.
Day-of-week discounts enable partners to set discount percentages for specific
days of the week. The day fields specify the discount for that day of the week
for the travel dates (such as Mondays at 15%, Tuesdays at 10% discount).
Exception (blackout) dates for which the promotion should NOT apply. This
field is only returned when querying for a single promotion (by specifying the promotion ID).
Promotion code that travelers will use to apply the promotion. This field is
returned in our booking APIs if a reservation is created for a product that
has an active promotion. It is returned in PromotionCode for the Booking
Notification API and in promoName for Booking Retrieval API. Note that only
these characters are supported: a-z, A-Z, 0-9, ., ,, ', :, !, ?, $, %, (, ),
/, -, and space.
Whether the promotion is currently bookable based on the its reservation
date/time range. This field is supported in queries only. All dates and times
are relative to the property’s time zone. The promotion may still be
unavailable due to other restrictions. At the time of querying, if the
promotion's bookingLocalDateTimeFrom and bookingLocalDateTimeTo values are
in the past but the travelDateFrom and travelDateTo values are in the
future, the promotion is considered expired because the promotion can no
longer be made available.
Whether registration is required by the jurisdiction. This is based on the geo
code of the property’s address, not the property type (for example,
registration may be required for a hotel but not a vacation rental in a
specific area).
The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.
Reason why the reservation cannot be reconciled. Values include the following:
GUEST_REQUESTED_CANCEL - Traveler cancelled the reservation
NO_SHOW - Traveler was a no-show
MODIFY_DATES_AMOUNTS - There was a difference in the booking price when the
lodging partner charged the traveler (for example, because an extra night was
added at the time of stay)
Property type for the district. This type provides what’s possible for the
district. Then, qualifiedPropertyTypes indicates the type and subtype at the
unit level. If subtype is set for the property, you should use both type and subtype.
Field
Description
subtype
Legal property subtype, applicable for residences, such as primary home or
secondary home. (This field provides the value that is specified in the
registration:details:regulatorySubType field of the updateUnitRegistration mutation.)
Legal property type, such as hotel, bed and breakfast, residence, etc. (This
field provides the value that is specified in the
registration:details:regulatoryType field of the updateUnitRegistration mutation.)
Whether the discount applied on the applicable night is recurring. For
example, if applicableNight is set to 3 and isRecurring is set to true,
the discount will be applied to the third, sixth, ninth nights (and so on).
Additional discount that is added to value for members only. For example, if
value is 10, unit is PERCENT, and memberOnlyAdditionalValue is 5,
members are offered 15 percent off.
Status of the response. The following values may be returned: APPROVED,
BEFORE_SUBMITTED_FOR_MODERATION, QUEUED_FOR_LANG_DETECT, REJECTED,
BEFORE_SUBMITTED_TO_ES, SUBMITTED, and REMOVEDBYCLIENT.
Be aware that reviews may be pending for up to 14 days depending on lodging partner actions and review content.
Whether the promotion is currently bookable based on the its reservation
date/time range. This field is supported in queries only. All dates and times
are relative to the property’s time zone. The promotion may still be
unavailable due to other restrictions. At the time of querying, if the
promotion's bookingLocalDateTimeFrom and bookingLocalDateTimeTo values are
in the past but the travelDateFrom and travelDateTo values are in the
future, the promotion is considered expired because the promotion can no
longer be made available.
Priced (discount) promotion. That is, the traveler benefit here is monetary savings via promotions.
PromotionName
Enum
Name
Description
BASIC_PROMOTION
Flexible offer with restrictions defined by the connectivity or lodging
partner. You can specify this value when creating or updating single and
day-of-week discounts.
EARLY_BOOKING_PROMOTION
Discount offered to travelers who want to book early. You can specify this
value when creating or updating single and day-of-week discounts only.
MULTI_NIGHT_PROMOTION
Multi-night discount that offers a percentage-based discount for applicable
nights. You can specify this value when creating or updating multi-night
discounts only.
SAME_DAY_PROMOTION
Discount offered to attract last-minute travelers by setting up a recurring
deal when the travel date is the same as the booking date. You can specify
this value when creating or updating single discounts only.
Values to indicate whether a promotion is currently bookable based on the its reservation date/time range.
Name
Description
EXPIRED
Promotion cannot be booked because today’s date is after the promotion's bookingLocalDateTimeTo.
CURRENT
Promotion can be booked because today’s date is between the promotion's
bookingLocalDateTimeFrom and .bookingLocalDateTimeTo.
FUTURE
Promotion cannot be booked yet because today's date is before the promotion's
bookingLocalDateTimeFrom. However, this promotion will become available to
book in the future.
PromotionStatus
Enum
Name
Description
ACTIVE
INACTIVE
Property
Object
Representation of a physical property, including its units, reservations, and promotions.
Field
Description
activeStatus
Status of the property on all platforms and property content.
Regulatory requirements and parameters that apply to the property. You can
specify the locale argument to retrieve the results in a specific language;
specify the four-letter ISO code for language. Use a four-character code that
indicates language and region, such as fr_FR for French in France.
Traveler-facing listing URLs of the property on the requested domains. Specify
the domains argument (type: String!) and provide one or both of these
values: expedia.com, vrbo.com. If you specify expedia.com, the API returns a
listing URL if the property exists an Expedia site. If you specify vrbo.com,
a listing URL is returned if the property exists on a Vrbo site.
List of promotions that matches the specified arguments. You can specify these arguments:
filter (type: FiltersInput), which enables you to refine the promotions to retrieve.
pageSize (type: Int!), which is required and specifies the maximum number
of promotions on each page (up to 25) returned by the response. For example,
if there are 40 promotions on a property, you can retrieve two pages if this
argument is set to 25 (page 1 includes 25 promotions, page 2 includes 15 promotions).
after (type: String), which is the cursor from the previous query response
that marked the end of the previous page of results.
List of the property's reservations that match the specified arguments:
filter (type: ReservationFilterInput), which enables you to refine the
reservations to retrieve. If this argument is not specified, the query returns
all reservations for the property.
pageSize (type: Int!), which is required and specifies the maximum number
of reservations on each page (up to 25) returned by the response. For example,
if there are 40 reservations on a property, you can retrieve two pages if this
argument is set to 25 (page 1 includes 25 reservations, page 2 includes 15 reservations).
after (type: String), which is the cursor from the previous query response
that marked the end of the previous page of results.
Reviews provided by travelers for the property that match the specified arguments. You can specify these arguments:
filter (type: ReviewFilter), which provides additional arguments to filter the reviews that are returned by the query.
pageSize (type: Int!), which is required and specifies the maximum number
of reviews on each page (up to 10) returned by the response. For example, if
there are 15 reviews on a property, you can retrieve two pages if this
argument is set to 10 (page 1 includes 10 reviews, page 2 includes 5 reviews).
after (type: String), which is the cursor from the previous query response
that marked the end of the previous page of results.
orderBy (type: ReviewsOrderBy), which provides the sort order of results;
only one field should be specified. If not specified, reviews are sorted by
review creation dateTime.
Reason why the reservation can be reconciled. Values include the following:
GUEST_REQUESTED_CANCEL - Traveler cancelled the reservation
NO_SHOW - Traveler was a no-show
MODIFY_DATES_AMOUNTS - There was a difference in the booking price when the
lodging partner charged the traveler (for example, because an extra night was
added at the time of stay)
Checks the consistency of the information in our systems at the property level
to determine whether the registration information is sufficient to fulfill the
requirements of the property's district. We do not recommend including this
field in the query because it does not provide the true value for some properties.
If false is returned for a unit, you can use the Product API to identify
active units, though false may be returned for inactive units that have
incorrect regulatory information.
Compliance status according to the local jurisdiction's regulatory requirements.
This object returns a non-compliant status for mandatory requirements only. If
invalid information is provided for an optional regulatory requirement, or if
regulatory information is set in a jurisdiction that does not require
regulatory information, status: COMPLIANT will be returned. However, for
optional requirements, a warning is returned in the warningStatus field when
the data is set (using the updateUnitRegistration mutation).
Note: We strongly recommend that you include this field in your
implementation even though it is nullable. This field provides an audit trail
for reporting purposes.
Registration number type. (This field provides the value that is specified in
the registration:details:registrationRecords:registrationNumberType field of
the updateUnitRegistration mutation.)
Category values for regulatory categories. Most of jurisdiction districts only
allow for two categories, HOTEL and VACATION_RENTAL, though more values
GRAPHQL_VALIDATION_FAILED are provided to satisfy local government requirements.
Name
Description
HOTEL
BED_AND_BREAKFAST
HOTEL_OR_BNB
PRIMARY_HOME
PRIMARY_HOME_WITH_EXCEPTION
SECONDARY_HOME
VACATION_RENTAL
LONG_TERM_ONLY
SHORT_TERM_RENTAL
MINPAKU
SIMPLE_LODGING
EVENT
SPECIAL
NO_LICENSE
HOTEL_RYOKAN
RYOKAN
PRIMARY_OR_SECONDARY
TRANSIENT_OCCUPANCY_RESIDENTIAL_STRUCTURE
MOTEL
HOME_SHARING_NUMBER
VACATION_RENTAL_OTHER
HOSTEL
CAMPING_SITES
RURAL_LODGING
APARTMENT_HOTEL
RegulatoryStatus
Enum
Values for regulatory status.
Name
Description
COMPLIANT
Unit meets all regulatory requirements.
COMPLIANT_ACTION_NEEDED
Unit meets requirements to remain listed but will need to provide
additional information (or other action) in order to not be delisted.
NOT_COMPLIANT
Unit does not meet all regulatory requirements and cannot be shown.
NOT_COMPLIANT_ACTION_NEEDED
Unit is not compliant, but enforcement hasn't started yet. Action should be
taken for the listing to be compliant after enforcement date.
NOT_ALLOWED
Platform does not allow units in this jurisdiction; no actions from partner can affect status.
NONE
Unit's status cannot be determined.
Reservation
Object
Reservation details.
Field
Description
accessibilityText
Accessibility requests made by the guest for the reservation. We strongly
recommend that you include this field in your implementation.
ID of the rate/rate plan and the source of the ID. In the response, when
idSource is set to SUPPLIER, the id field returns the same value as
returned by the existing booking APIs. However, for Hotel Collect properties,
the A- prefix is no longer added to the ‘source’ value and the A suffix is no
longer appended to the rate ID as was done by the booking APIs.
Value add promotion(s) used to book the reservation. If a value add promotion
(VAP) was not used, an empty array is returned. We strongly recommend that you
include this field in your implementation.
Resolution status values, which indicate the API's ability to determine if a checkpoint is fulfilled.
Name
Description
RESOLVED
Checkpoint was successfully evaluated.
UNRESOLVED_PROPERTY_NOT_PROVISIONED
API could not determine a fulfilled value because the property is missing from
our internal system. Retry the operation; this is typically caused by a
transient internal error. If the error persists, contact your Technical
Relationship Manager.
UNRESOLVED_CHECKPOINT_SYSTEM_UNAVAILABLE
API could not determine a fulfilled value because of an internal problem.
Retry the operation; this is typically caused by a transient internal error.
If the error persists, contact your Technical Relationship Manager.
Restrictions
Object
Field
Description
bookingLocalDateTimeFrom
Beginning of the date range (inclusive) when the reservation can be made in
order for this promotion to be applicable. Format is YYYY-MM-DDThh:mm:ss, in
the property’s local time zone.
End of the date range (inclusive) when the reservation can be made in order
for this promotion to be applicable. Format is YYYY-MM-DDThh:mm:ss, in the
property’s local time zone.
Whether this promotion is applicable only to travelers booking on the mobile
device. This field is returned when querying for a single promotion only (by
specifying the promotion ID).
Checkpoint is fulfilled (fulfilled equal to true).
FAILED
Checkpoint is not fulfilled (fulfilled equal to false). This means the
content requirement has not been met. Verify that content is included in the
Listings integration file for processing.
UNRESOLVED
API could not determine the checkpoint's fulfilled value (resolutionStatus
equal to UNRESOLVED_*). Retry the operation; this is typically caused by a
transient internal error. If the error persists, contact your Technical
Relationship Manager.
Review
Object
Review content, including its source, localized text, and reservation information to which it pertains.
Brand to which the review belongs. Values include Aago, BedandBreakfast,
CheapTickets, Ebookers, Expedia, HomeAway, Hotels, Lastminute, MrJet, Orbitz,
Travelocity, Venere, VSC, and Wotif.
Discount that offers a percentage off a rate (such as 15% off).
Field
Description
memberOnlyAdditionalValue
Value of member-only discount applied. For example, if the regular discount is
10% and memberOnlyAdditionalValue is set to 5, a member will receive a 15%
discount and a non-member will receive a 10% discount.
Sort results in ascending order (oldest to newest).
DESC
Sort results in descending order (newest to oldest).
StatusCheckpoint
Object
Information about a property's or unit's content requirements (checkpoints).
Field
Description
checkpointByName
Checkpoint specified by name. This field requires an argument:
checkpointByName(name: String!). Refer to the name field below for the
list of values that can be used.
Content requirement (checkpoint) that determines overall status. This field
provides an optional argument, checkpoints(filter: CheckpointFilter), which
enables you to filter the returned checkpoints by result. Refer to the
CheckpointFilter type for details.
Whether the checkpoint conditions were satisfied. If false, the content
requirement has not been met; verify that content is included in the Listings
integration file for processing.
Checkpoint name. Here is the list of checkpoints that may be returned, by
onbaording source. For information about the minimum requirements that must be
met for each checkpoint, see Intro to property status.
Note: Not all checkpoints are included in every response, and this list
may not be definitive. Assumptions about the presence of any of these
checkpoints should not be built into logic.
For properties onboarded on Expedia, these checkpoints may be returned:
BEXPropertyIsEnabledPredicate - Top-level checkpoint and "container" of all others.
BEXHasPropertyOnboarded, which relies on the following required minimum
content checkpoints are fulfilled and were provided by the partner during onboarding:
HasActiveImages
HasActiveRoom
HasAddress, which relies on the following checkpoints:
HasPropertyTaxes, which relies on the HasLodgingTax checkpoint
HasRegulatory
HasStructureType
BEXHasStopSellDisabled - No external services have set stop-sell on the
property. This checkpoint is generated internally and cannot be updated by the partner.
HasProviderConfigured - An active provider exists for the property. This
checkpoint is generated internally by Expedia based on internal processes; it
cannot be updated by the partner. Contact your Technical Relationship Manager
if you have issues with this checkpoint.
IsPCOOnboarded - The property has completed the prelive step of Partner
Central Onboarding, which determines if the IsPCOPublishSubmitted checkpoint
is required. This checkpoint is generated internally and cannot be updated by
the partner, and it is not applicable for properties that were onboarded using the API.
IsNotPCOOnboarded - The property has not completed the prelive step of
Partner Central Onboarding. If this is fulfilled, IsPCOPublishSubmitted is
not required. This checkpoint is generated internally and cannot be updated by
the partner, and it is not applicable for properties that were onboarded using the API.
IsPCOPublishSubmitted - The partner has clicked the "publish" button at
the end of Partner Central Onboarding. This checkpoint is generated internally
and cannot be updated by the partner.
For properties onboarded on Vrbo, these checkpoints may be met at the property level:
IsPropertyLive - Top-level checkpoint and "container" of all others
IsNotDeleted - The listing exists (is not deleted)
HasNotCancelledSubscriptions - Listing subscriptions have not been
cancelled (though a listing may be inactive for reasons other than
cancellation, such as expired subscription)
IsAccountNotDelinquent - The listing does not have violations
HasBookableUnit - The listing has units that are enabled and bookable.
However, a unit may be considered bookable by our system, though it may not
actually be bookable for other reasons, such as being archived.
IsActiveByOwner - The listing is not deactivated by the property manager
IsListingNotArchived - The listing is not archived (archived listings are
inactive, and they are not available in search of the Vrbo dashboard)
IsActiveByCsr - The listing is not deactivated by a customer service representative
HasActiveSubscription - The listing has a valid subscription and is active
(though a listing may be inactive for reasons other than cancellation, such as
expired subscription)
HasActiveUnit - The listing has a unit and it is enabled. However, a unit
may be considered bookable by our system, though it may not actually be
bookable for other reasons, such as being archived.
IsMinimumContentProvided - The listing has met the minimum content requirements
IsPpbListing - The listing has the pay-per-booking (PPB) payment type defined
IsNotPpbListing - The listing does not have the pay-per-booking (PPB) payment type defined
IsPreviewListing - The listing has a product type of "preview"
IsNotPreviewListing - The listing does not have a product type of "preview"
IsRenewable - The listing is renewable
IsSubscriptionBasedListing - The listing has payment terms (of type SUBSCRIPTION) defined
IsTrustedPmListing - The listing belongs to a trusted partner
IsUserNfmp - User is flagged as "not fair market practice"
IsMerchantAccountNotRevoked - The listing's merchant account has not been revoked
AdvertiserReadyToPublish - The listing's property manager has a valid publish date
HasActivePPSV2Subscription - The listing has a valid subscription of type SUBSCRIPTION_V2
HasCurrentEntitlements - The listing has a current active entitlement
(entitlement is required for each listing's subscription)
HasMatchingListProductType - The listing's product type matches the entitlement type
HasPendingOrActiveSubscription - The listing has a pending or active subscription
HasSubscription - The listing has a subscription
For properties onboarded on Vrbo, these checkpoints may be met at the unit level:
HasUnitMinimumContentProvided - Top-level checkpoint and "container" of all others
HasImages - Minimum content requirement of six images has been met
HasBookingType - The booking policy is set for the property (INSTANT or QUOTEHOLD)
HasLocation, which relies on these checkpoints:
HasValidatedAddress - Unit has valid, stored address and geolocation data upon lookup
HasGeoCode - Unit has valid and stored latitude and longitude
HasPropertyAddress - Unit has a valid and stored property address
HasPropertyDetails, which relies on these checkpoints:
HasBathroom - Unit has at least one bathroom defined
HasMaxOccupancy - Unit has valid maximum occupancy defined
HasPropertyDescription - Unit has met minimum content requirement for a description
HasPropertyHeadline - Unit has met minimum content requirement for the headline
HasPropertyName - Unit has met minimum content requirement for the property name
HasPropertyType - A valid property type enumeration is defined
HasPropertyContact - At least one form of contact is defined for the property
HasRates - Unit has met minimum requirement for valid and stored rates
HasRegistrationNumber - Unit has a valid and stored registration number, if required by the property's jurisdiction
HasHouseRules - House rules are defined for the unit
HasCancellationPolicy - Cancellation policy is defined for the unit
NotRegulatoryDelistRequest - Unit was delisted by regulatory operations
Ordered list of parent checkpoint nodes in the status calculation tree. If you
need to reconstruct the tree, discover added context about a checkpoint, or
make use of the checkpointByName field, then this information may be useful.
The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.
Nightly rate with no additional taxes, fees, or surcharges.
EXTRA_GUEST_FEES
Fees that are included in the price that guests see when booking. They are
paid in advance for Expedia Collect reservations or upon arrival for Hotel
Collect reservations.
SERVICE_FEES
Fees that only apply to guests who make use of specific facilities or
services, such as resort fees, parking fees, or fees for rollaway beds.
RECONCILED_AMOUNT
Updated rate, which must be the commissionable value for the stay date.
Amounts for dates included in the original reservation cannot be modified to a
value of three times more than the commissionable rate applicable to that date.
SupplierRate
Object
Field
Description
fromDate
Not nullable.
Date when the rate becomes effective (format: YYYY-MM-DD).
Registration information for the unit or room type. You can specify the
locale argument to retrieve the results in a specific language; specify the
four-letter ISO code for language. Use a four-character code that indicates
language and region, such as fr_FR for French in France.