Intro to compliance
The Lodging Supply GraphQL API provides visibility into regulatory information for jurisdictions where properties will be listed. The goal of the compliance capability is to manage EG regulatory information within software, provide real-time EG regulatory requirements, assist in validating status, and increase operational efficiency. After you have integrated this API, lodging partners can
- Query for regulatory requirements for a given property or jurisdiction
- Add or update regulatory data on the property to meet mandatory requirements
- Retrieve status and details about a property's registration
- Validate registration status against EG requirements
Importantly, you can use the capability's queries to review regulatory information that can be defined for a property, such as its entity type and location. Based on that, you can set regulatory data on the property to meet mandatory requirements, such as those defined in Europe (the DAC7 directive), France, San Diego, London, Tasmania, and Australia. See Fulfilling DAC7 requirements (below) for an example.
The compliance capability is part of the Lodging Supply GraphQL API, which enables connectivity providers to retrieve and manage property and reservation information. All response bodies, including errors, are encoded in JSON. All requests and responses must be made over a secure connection.
If you are unfamiliar with GraphQL concepts, such as queries and mutations, read this overview to learn more.
Important: Partners must not put Expedia in breach of any privacy or data protection laws. Therefore, to maintain the highest standards of data protection and privacy compliance (such as upholding data minimization, ensuring an appropriate lawful basis is relied upon and robust security measures are in place), we require that partners DO NOT use real personal data under any circumstances during the testing and certification process. Instead, we require partners to use dummy data, fictitious information, or data specifically designated for testing and certification purposes so that no personal data is accessed, shared, and/or reused between partners unnecessarily and unlawfully.
Limitations
Be aware of these as you integrate the compliance capability:
- This capability is not supported for properties in Japan. In general, the capability is only supported for properties in jurisdictions that are supported by our underlying regulatory service.
- The capability is not tied to the go-live workflow, which means that non-compliant properties are not automatically delisted at this time.
- Registration information is updated at the room-type level. Updating registration information at the property level is not supported.
Minimum certification requirements
Partners who want to adopt the compliance capability are required to successfully complete end-to-end certification with Expedia Group teams. Specifically, the partner be able to
Read regulatory requirements by property ID or by jurisdiction.
Read compliance status for each active unit of a property. Note that the query to retrieve a property's registration information at the unit (room type) level will return information for all units, active and inactive. Use the Product API for to identify the correct active unit ID before updating registration information.
Add or update each active unit in a jurisdiction with mandatory requirements. Ensure the following is in place:
- Correct registration information
- All mandatory regulatory information; for example, some jurisdictions have additional regulatory information (
regulatorySubType
or more than oneregistrationNumberRequirements
)
Include
warningStatus
in your implementation to ensure that warnings are captured.Implement a synchronization process for properties with mandatory regulatory requirements to capture non-compliant active units and add or update registration on regular basis. Refer to Updating registration information for details.
Retrieving regulatory requirements
You can query for regulatory requirements in two ways:
- By property ID
- By jurisdiction
By property ID
The district
query retrieves regulatory requirements at the property level for the specified property's jurisdiction. In this request example, the locale
argument on district
retrieves the results in US English (en_US).
Be aware that compliance requirements differ by country. For example, in France, it is mandatory for a unit to be assigned regulatorySubType
, which is not applicable to Spanish properties (regulatorySubType
is null). And the regulatoryCategory
value varies across countries and depends on the registrationNumberRequirements
.
Here is an explanation of the response:
- Registration is required (
"registrationRequired": true
) for residences and hotels (legalPropertyTypes
object). - 16 registration requirements are listed for both types of properties (under each
registrationNumberRequirements
array). - To understand how to interpret the information for each requirement, consider these examples:
- For registration number (
"numberType": "REGISTRATION_NUMBER”
):- This is also referred to as VAT or tax ID (
"localName": "VAT or Tax ID”
), and it is mandatory ("isOptional": false
). - Three examples are given for the registration number format (
"format": "123456789, HR1234567890123, 123456789ABCDEFGHI"
) and the regular expression that describes this format is provided ("regex": "^[a-zA-Z0-9]{8,18}$"
). - No expiration date is required (
"isExpirationDateRequired": false
). - Pending registrations are not allowed (
"allowPendingRegistrations": false
).
- This is also referred to as VAT or tax ID (
- For entity type (
"numberType": "ENTITY_TYPE”
):- This is optional (
"isOptional": true
). - In Expedia Partner Central (EPC), this is set by the "Are you a business or an individual?" question, and the acceptable values include "Individual" and "Business".
- No expiration date is required (
"isExpirationDateRequired": false
). - Pending registrations are not allowed (
"allowPendingRegistrations": false
).
- This is optional (
- For property address (
"numberType": "LEGAL_ADDRESS”
):- This is not required as part of its regulatory information (
"isOptional": true
). - In EPC, the address is set by the "What is your legal business address or legal registered address?" question.
- The submitted values are validated by this regular expression: ^.{1,240}$.
- No expiration date is required (
"isExpirationDateRequired": false
). - Pending registrations are not allowed (
"allowPendingRegistrations": false
).
- This is not required as part of its regulatory information (
- For registration number (
- Request
- Response
1query {2 property(id: "53185459", idSource: EXPEDIA) {3 geoLocation {4 latitude5 longitude6 }7 district(locale: "en_US") {8 id9 description10 nativeLocale11 localizedName12 referenceUrls13 registrationRequired14 legalPropertyTypes {15 type16 subtype17 }18 requirements {19 regulatoryCategory20 regulatoryCategoryLabel21 qualifiedPropertyTypes {22 type23 subtype24 }25 registrationNumberRequirements {26 numberType27 numberTypeLabel28 localName29 format30 regex31 isOptional32 isExpirationDateRequired33 allowPendingRegistrations34 url35 thirdPartyValidation {36 required37 attributes38 }39 }40 additionalDataRequirements {41 key42 keyLocalized43 type44 typeLocalized45 subtype46 subtypeLocalized47 group48 groupLocalized49 isOptional50 }51 minStayNights52 maxNightCap {53 annualLimit54 isEnforced55 }56 exemptions {57 category58 description59 }60 isVacationRental61 }62 }63 }64}
By jurisdiction
Issue the districtByCoordinates
query to retrieve a jurisdiction's regulations. This is useful if a lodging partner wants to review requirements before listing properties in a jurisdiction.
These examples retrieve all regulatory information for the specified jurisdiction, such as allowed property types, registration numbers, and minimum and maximum length-of-stay requirements. The responses show requirements for hotels and vacation rentals.
- Request - Maui
- Response
- Request - Miami Beach
- Response
- Request - Boston
- Response
1query {2 districtByCoordinates(3 latitude: 20.7983624 longitude: -156.3319265 locale: "en_US"6 ) {7 id8 description9 nativeLocale10 localizedName11 referenceUrls12 registrationRequired13 legalPropertyTypes {14 type15 subtype16 }17 requirements {18 regulatoryCategory19 regulatoryCategoryLabel20 qualifiedPropertyTypes {21 type22 subtype23 }24 registrationNumberRequirements {25 numberType26 numberTypeLabel27 localName28 format29 regex30 isOptional31 isExpirationDateRequired32 allowPendingRegistrations33 url34 thirdPartyValidation {35 required36 attributes37 }38 }39 additionalDataRequirements {40 key41 keyLocalized42 type43 typeLocalized44 subtype45 subtypeLocalized46 group47 groupLocalized48 isOptional49 }50 minStayNights51 maxNightCap {52 annualLimit53 isEnforced54 }55 exemptions {56 category57 description58 }59 isVacationRental60 }61 }62}
Retrieving a property's registration information and compliance status
Use the registration
query to retrieve a property's registration information at the unit (room type) level. This is useful in confirming a unit's information and determining its jurisdiction's requirements. The API returns the registration information in our system for all active and inactive units (room types) on the property.
The following example retrieves registration information for the Croatian property used in the district
query above. The response shows
- Unit is compliant (
"status": "COMPLIANT"
) because a registration number is provided in a valid format (as described in thereason
field) - Two registration records are set on the unit: REGISTRATION_NUMBER and ENTITY_TYPE
Note that the complete
field is not included in the query because it reports information at a property level and does not provide the true value for some properties.
- Request
- Response
1query {2 property(id: "53185459", idSource: EXPEDIA) {3 id4 name5 units {6 ids {7 id8 idSource9 }10 registration {11 district12 detail {13 compliant {14 status15 reason16 }17 regulatoryCategory18 numberOfPhysicalRooms19 registrationRecords {20 registrationNumber21 registrationNumberType22 registrationNumberTypeLabel23 expiry24 }25 }26 }27 }28 }29}
Updating registration information
Use the updateUnitRegistration
mutation to update registration information at the room type (unit) level.
- If an empty or invalid registration number is specified in the mutation, warnings are generated. We strongly recommend that you include
warningStatus
in your implementation to ensure that you capture warnings if they are generated.warningStatus
is a field on theUnitRegistrationDetail
object. - If the specified room type ID does not belong to the specified property, an error is generated.
To determine the registration requirements to set using the updateUnitRegistration
mutation, you must
- Examine the
requirements
object in thedistrictByCoordinates
ordistrict
query’s response. - For each regulatory category, review the value of
registrationNumberRequirements
:isOptional
. - When
isOptional
is set tofalse
, you must set registration numbers for those registration number types.
To continue with the example above, the following mutation sets all of the regulatory information required by the DAC7 mandate:
- Request
- Response
1mutation {2 updateUnitRegistration(3 propertyId: "53185459"4 propertyIdSource: EXPEDIA5 forceSave: false6 registration: {7 details: [8 {9 unitId: "324183846"10 regulatoryType: "residence"11 regulatorySubType: ""12 regulatoryCategory: VACATION_RENTAL13 numberOfPhysicalRooms: 114 registrationRecords: [15 {16 registrationNumber: "123456789"17 registrationNumberType: REGISTRATION_NUMBER18 },19 {20 registrationNumber: "Individual"21 registrationNumberType: ENTITY_TYPE22 },23 {24 registrationNumber: "Yes"25 registrationNumberType: IS_ADDRESS_IN_EU26 },27 {28 registrationNumber: "No"29 registrationNumberType: IS_RESIDENCE_IN_EU30 },31 {32 registrationNumber: "Test street 11, Dubrovnik, Croatia, postcode 2345"33 registrationNumberType: LEGAL_ADDRESS34 },35 {36 registrationNumber: "AB:Product123"37 registrationNumberType: ISSUED_TAX_ID38 }39 {40 registrationNumber: "BB 1234567 098765 registration"41 registrationNumberType: LAND_REGISTRATION_NUMBER42 },43 {44 registrationNumber: "1992-01-22"45 registrationNumberType: BIRTH_DATE46 },47 {48 registrationNumber: "Yes"49 registrationNumberType: IS_VAT_REGISTERED50 },51 {52 registrationNumber: "ExampleVAT123"53 registrationNumberType: VAT_ID54 }55 ]56 }57 ]58 }59 ) {60 complete61 details {62 compliant {63 status64 reason65 }66 warningStatus {67 description68 code69 }70 unitId71 regulatoryCategory72 regulatoryType73 regulatorySubType74 regulatoryCategoryLabel75 registrationRecords {76 registrationNumber77 registrationNumberType78 registrationNumberTypeLabel79 }80 }81 }82}
Here are additional examples:
- Request - Hotel
- Response
- Request - San Diego VR
- Response
- Request - Australian VR
- Response
1mutation {2 updateUnitRegistration(3 propertyId: "9309956",4 propertyIdSource: EXPEDIA,5 forceSave: false,6 registration: {7 details: [8 {9 unitId: "200299052",10 regulatoryType: "hotel",11 regulatoryCategory: HOTEL,12 registrationRecords: [13 {14 registrationNumber: "HSR12-34567"15 }16 ]17 }18 ]19 }20 ) {21 complete22 details {23 unitId24 compliant {25 status26 reason27 }28 registrationRecords {29 registrationNumber30 }31 warningStatus {32 description33 code34 }35 }36 }37}
Retrieving compliance and property status information
If you have implemented the property status capability, you can retrieve property status and compliance information using one query. The following query retrieves this information:
- Vrbo listing URL
- Expedia distributed URL
- Whether the property is live on Expedia (
BEXPropertyIsEnabledPredicate
checkpoint has"fulfilled": true
) - Whether the property is compliant with local regulations: (
registration : detail : compliant : status
) - If not compliant, a link to local regulatory laws (
district : referenceUrls
)
- Request
- Response
1query {2 property(id: "34479786", idSource: EXPEDIA) {3 name4 coordinates {5 latitude6 longitude7 }8 district(locale: "fr_FR") {9 id10 referenceUrls11 }12 listings(domains: ["expedia.com"]) {13 url14 }15 activeStatus {16 active17 statusCheckpoint {18 name19 lastEvaluated20 resolutionStatus21 checkpoints {22 name23 path24 lastEvaluated25 resolutionStatus26 fulfilled27 }28 }29 }30 }31}
Fulfilling DAC7 requirements
The Directive on Administrative Co-operation (DAC7) is a European regulatory mandate that enforces annual reporting obligations for digital online platforms, crypto-assets and e-money (full details here). The directive requires digital platform operators in the EU (including all Expedia Group sites) to collect and report personal and business income information realized by sellers using their platforms for certain commercial services. The goal is to ensure all taxes — income tax as well as value-added tax (VAT) — are reported and assessed.
The compliance capability provides the district
and districtByCoordinates
queries to retrieve regulatory information that can be set for a property as defined by its jurisdiction. This might include a property's entity type, location, and various registration numbers. You should implement your UI so that the lodging partner can provide data for each of the regulatory requirements reported by the query.
As an example, the district
query above shows that the following regulatory information can be set for vacation rentals and hotels located in Croatia:
- REGISTRATION_NUMBER
- ENTITY_TYPE
- IS_TRADED
- IS_GOVERNMENT_ENTITY
- IS_ADDRESS_IN_EU
- IS_RESIDENCE_IN_EU
- LEGAL_ADDRESS
- ISSUED_TAX_ID
- PERMANENT_ESTABLISHMENT_COUNTRY
- BUSINESS_REGISTRATION_NUMBER
- BUSINESS_ISSUING_REGISTRY
- LAND_REGISTRATION_NUMBER
- BIRTH_DATE
- IS_VAT_REGISTERED
- VAT_ID
- AUSTRALIAN_BUSINESS_NUMBER
The data that must be set for a property to meet the DAC7 mandate will depend on values provided for each regulatory requirement listed here.
If these values are provided for a property: | Set this regulatory information: |
---|---|
ENTITY_TYPE: Business or ENTITY_TYPE: Business |
|
ENTITY_TYPE: Individual or ENTITY_TYPE: Individual |
|
Use the updateUnitRegistration
mutation to set regulatory data on the property. To continue with our example, the mutation above sets all of the regulatory requirements for a vacation rental in Croatia.