Intro to complianceCopy link

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.

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 one registrationNumberRequirements)

• 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).
  • 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).
  • 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).

1query {
2  property(id: "53185459", idSource: EXPEDIA) {
3    geoLocation {
4      latitude
5      longitude
6    }
7    district(locale: "en_US") {
8      id
9      description
10      nativeLocale
11      localizedName
12      referenceUrls
13      registrationRequired
14      legalPropertyTypes {
15        type
16        subtype
17      }
18      requirements {
19        regulatoryCategory
20        regulatoryCategoryLabel
21        qualifiedPropertyTypes {
22          type
23          subtype
24        }
25        registrationNumberRequirements {
26          numberType
27          numberTypeLabel
28          localName
29          format
30          regex
31          isOptional
32          isExpirationDateRequired
33          allowPendingRegistrations
34          url
35          thirdPartyValidation {
36            required
37            attributes
38          }
39        }
40        additionalDataRequirements {
41          key
42          keyLocalized
43          type
44          typeLocalized
45          subtype
46          subtypeLocalized
47          group
48          groupLocalized
49          isOptional
50        }
51        minStayNights
52        maxNightCap {
53          annualLimit
54          isEnforced
55        }
56        exemptions {
57          category
58          description
59        }
60        isVacationRental
61      }
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.

1query {
2  districtByCoordinates(
3    latitude: 20.798362
4    longitude: -156.331926
5    locale: "en_US"
6  ) {
7    id
8    description
9    nativeLocale
10    localizedName
11    referenceUrls
12    registrationRequired
13    legalPropertyTypes {
14      type
15      subtype
16    }
17    requirements {
18      regulatoryCategory
19      regulatoryCategoryLabel
20      qualifiedPropertyTypes {
21        type
22        subtype
23      }
24      registrationNumberRequirements {
25        numberType
26        numberTypeLabel
27        localName
28        format
29        regex
30        isOptional
31        isExpirationDateRequired
32        allowPendingRegistrations
33        url
34        thirdPartyValidation {
35          required
36          attributes
37        }
38      }
39      additionalDataRequirements {
40        key
41        keyLocalized
42        type
43        typeLocalized
44        subtype
45        subtypeLocalized
46        group
47        groupLocalized
48        isOptional
49      }
50      minStayNights
51      maxNightCap {
52        annualLimit
53        isEnforced
54      }
55      exemptions {
56        category
57        description
58      }
59      isVacationRental
60    }
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 the reason 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.

1query {
2  property(id: "53185459", idSource: EXPEDIA) {
3    id 
4    name 
5    units { 
6      ids { 
7        id 
8        idSource 
9      } 
10      registration { 
11        district 
12        detail { 
13          compliant { 
14             status 
15             reason 
16          } 
17          regulatoryCategory 
18          numberOfPhysicalRooms 
19          registrationRecords { 
20            registrationNumber 
21            registrationNumberType
22            registrationNumberTypeLabel 
23            expiry 
24          } 
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 the UnitRegistrationDetail 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

1. Examine the requirements object in the districtByCoordinates or district query’s response.
2. For each regulatory category, review the value of registrationNumberRequirements : isOptional.
3. When isOptional is set to false, 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:

1mutation {
2  updateUnitRegistration(
3    propertyId: "53185459"
4    propertyIdSource: EXPEDIA
5    forceSave: false
6    registration: {
7      details: [
8        {
9          unitId: "324183846"
10          regulatoryType: "residence"
11          regulatorySubType: ""
12          regulatoryCategory: VACATION_RENTAL
13          numberOfPhysicalRooms: 1
14          registrationRecords: [
15            {
16              registrationNumber: "123456789"
17              registrationNumberType: REGISTRATION_NUMBER
18            },
19            {
20              registrationNumber: "Individual"
21              registrationNumberType: ENTITY_TYPE
22            },
23            {
24              registrationNumber: "Yes"
25              registrationNumberType: IS_ADDRESS_IN_EU
26            },
27            {
28              registrationNumber: "No"
29              registrationNumberType: IS_RESIDENCE_IN_EU
30            },
31            {
32              registrationNumber: "Test street 11, Dubrovnik, Croatia, postcode 2345"
33              registrationNumberType: LEGAL_ADDRESS
34            },
35            {
36              registrationNumber: "AB:Product123"
37              registrationNumberType: ISSUED_TAX_ID
38            }
39            {
40              registrationNumber: "BB 1234567 098765 registration"
41              registrationNumberType: LAND_REGISTRATION_NUMBER
42            },
43            {
44              registrationNumber: "1992-01-22"
45              registrationNumberType: BIRTH_DATE
46            },
47            {
48              registrationNumber: "Yes"
49              registrationNumberType: IS_VAT_REGISTERED
50            },
51            { 
52              registrationNumber: "ExampleVAT123"
53              registrationNumberType: VAT_ID
54            }
55          ]
56        }
57      ]
58    }
59  ) {
60    complete
61    details {
62      compliant {
63        status
64        reason
65      }
66      warningStatus {
67        description
68        code
69      }
70      unitId
71      regulatoryCategory
72      regulatoryType
73      regulatorySubType
74      regulatoryCategoryLabel
75      registrationRecords {
76        registrationNumber
77        registrationNumberType
78        registrationNumberTypeLabel
79      }
80    }
81  }
82}

Here are additional examples:

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    complete 
22    details { 
23      unitId 
24      compliant { 
25        status 
26        reason 
27      } 
28      registrationRecords { 
29        registrationNumber       
30      }
31      warningStatus { 
32        description 
33        code   
34      }     
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)

1query {
2  property(id: "34479786", idSource: EXPEDIA) {
3    name
4    coordinates {
5      latitude
6      longitude
7    }
8    district(locale: "fr_FR") {
9      id
10      referenceUrls
11    }
12    listings(domains: ["expedia.com"]) {
13      url
14    }
15    activeStatus {
16      active
17      statusCheckpoint {
18        name
19        lastEvaluated
20        resolutionStatus
21        checkpoints {
22          name
23          path
24          lastEvaluated
25          resolutionStatus
26          fulfilled
27        }
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.

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.