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.

Best practices

The compliance capability is fairly complicated and you need to be particularly mindful of several fields in the queries and mutation. Therefore, we are providing these best practices:

• To determine the registration requirements to set using the updateUnitRegistration mutation, you must

  1. Examine the requirements object returned by the districtByCoordinates or district query.
  2. For each regulatory category in requirements, review the value of registrationNumberRequirements : isOptional.
  3. When isOptional is set to false, you must set registration numbers for those registration number types.

• When implementing the updateUnitRegistration mutation, we strongly recommend that you include warningStatus in your implementation to capture warnings if they are generated. Note that warnings are different than errors; errors are described in Error handling.

• The updateUnitRegistration mutation includes the forceSave input argument, which forces the API to save the registration information for mandatory registration requirements even if the information is not valid.

  • If optional registration requirements need to be updated for a unit and forceSave is set to false, you must include the mandatory requirements in the request (even if there is no update to their values). If they are not specified, the mutation will fail and the optional requirements will not be not updated.
  • If forceSave is set to false and a value of a mandatory registration field is not valid, the value is not saved. If set to true, the value is saved. In both cases, warningStatus field will describe the issue in the response payload.
  • If a specified registration field is optional, the information is saved no matter how forceSave is set and the warning will indicate that the update was successful.

• If mandatory requirements are not specified when calling the updateUnitRegistration mutation, this warning is returned: "warningStatus": { "description": "Update Unsuccessful. Invalid registration details provided. Please provide valid details to ensure compliance.

• When implementing your UI, we strongly recommend that you visually distinguish mandatory fields to reduce unsuccessful updates. This is especially true when forceSave is set to false. Updates to registration information will fail unless mandatory fields are completed.

• The registration query and updateUnitRegistration mutation’s response payload provides a couple fields that may be confusing:

• The compliant object returns the compliance status for mandatory requirements only (at the unit level). 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 is returned. For optional requirements, a warning is returned in the warningStatus field of the mutation's payload.

• The complete field indicates whether a valid registration record was successfully written by the mutation. This field does not report whether the record fulfills the requirements of the property's district. Also, it reports information at the property level, though the property may contain deleted or inactive units and may provide inaccurate information for some properties. We do not recommend including this field.

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.