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

Workflow

1. Retrieve 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.

   • Request
   • Response
   • Copy

   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.

   • Request - Maui
   • Response
   • Request - Miami Beach
   • Response
   • Request - Boston
   • Response
   • Copy

   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}

2. Retrieve the 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 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.

   • Request
   • Response
   • Copy

   1query {
   2  property(id: "53185459", idSource: EXPEDIA) {
   3    id 
   4    name 
   5    unitsPaginated(
   6      filters: {status: {state: ALL}}
   7    ) {
   8      elements {
   9        ids { 
   10          id 
   11          idSource 
   12        } 
   13        registration { 
   14          district 
   15          detail { 
   16            compliant { 
   17              status 
   18              reason 
   19            } 
   20            regulatoryCategory 
   21            numberOfPhysicalRooms 
   22            registrationRecords { 
   23              registrationNumber 
   24              registrationNumberType
   25              registrationNumberTypeLabel 
   26              expiry 
   27            }
   28          } 
   29        } 
   30      } 
   31    } 
   32  } 
   33} 

3. Update registration information.

   Use the updateUnitRegistration mutation to update registration information at the unit level. To continue with the example above, the following mutation sets all of the regulatory information required by the DAC7 mandate:

   • Request
   • Response
   • Copy

   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:

   • Request - Hotel
   • Response
   • Request - San Diego VR
   • Response
   • Request - Australian VR
   • Response
   • Copy

   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} 

Implementation details and limitations

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

• The registration query and updateUnitRegistration mutation’s response provide 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.

Be aware of these limitations 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.

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.