Vrbo on Rapid Integration Guide

This article offers a guide to the Rapid 3.0 Vrbo integration process including how it works, example API requests and responses, limitations, common errors, support guidance, FAQs, and resources

Rapid API Vrbo-Specific Guidelines

Geography

Partners using Rapid Geography who are enabled for Vrbo will automatically see Vrbo property IDs returned by all Geography APIs alongside conventional lodging properties, such as hotels, and other vacation rental properties.

For those partners not using Rapid Geography APIs, please note that we are unable to expose property street addresses until a booking has been made. As such, partners should use the lat/long from the Content API in conjunction with your own geography solution to map properties.

Content

Vrbo inventory considerations:

• Content is available through the same API endpoints as native Rapid inventory. The key distinction is sending the supply_source parameter as Vrbo. Applies to the Content API, Content File, and Catalog File.
• Property names are often longer, e.g. ‘Fantastic apartment within walking distance of the wonderful Meia Praia beach'
• Property street addresses are not available in Rapid content. Full street addresses can be found in the Rapid Itinerary Retrieve API response post-booking.
• Business model for Vrbo properties may not be accurate. Business models for Vrbo supply are based on the property payment schedule and currency at time of shop, not at the property level. As such, any property can be Expedia Collect or Property Collect, depending on the booking window.

Fields which are relevant to Vrbo inventory:

• The following content fields may not appear for Vrbo properties:
  • Property Rating - Ratings are not available for Vrbo properties currently.
  • Room Description - Not relevant to single-unit vacation rental properties.
  • Rate Plan - Not relevant to Vrbo properties.
  • Room-Level Info - All room description information is available at the property level.
• Because there is no room level content for Vrbo properties, amenities that are usually on the room level are included in a new section called vacation_rental_details.

Vrbo or VR-specific fields in Rapid Content:

• registry_number is a required field for display of vacation rental properties. Please see launch requirements for more details.
• private_host_property (attribute ID 1073745102) and private_host_property (attribute ID 1073745142) are required for display, along with additional required descriptions. Please see launch requirements for more details.
• statistics includes information specific to the vacation rental unit, including max occupancy, number of bedrooms, number of bathrooms, number of rooms (1 when single unit VR), and property floor area (in square meters and feet).

Example:

"statistics": {
            "1073743380": {
                "id": "1073743380",
                "name": "Max occupancy - 15",
                "value": "15"
            },
            "1073743378": {
                "id": "1073743378",
                "name": "Number of bedrooms - 5",
                "value": "5"
            },
            "1073743379": {
                "id": "1073743379",
                "name": "Number of bathrooms - 5",
                "value": "5"
            },
            "52": {
                "id": "52",
                "name": "Total number of rooms - 1",
                "value": "1"
            },
            "1073743538": {
                "id": "1073743538",
                "name": "Property floor area (square meters) - 418",
                "value": "418"
            },
            "1073743537": {
                "id": "1073743537",
                "name": "Property floor area (square feet) - 4500",
                "value": "4500"
            }
        },

• property_manager includes the property manager name, image, and languages spoken when available.

Example:

"property_manager": {
                "name": "Susan Oakley/Property Administrator",
                "links": {
                    "image": {
                        "method": "GET",
                        "href": "https://mediaim.expedia.com/lodgingprofile/30634079/fd818c8c-a17a-47b6-bd42-fa7b71a935bc.c1.jpg"
                    }
                }
            },

• Bathroom and bedroom count:

  • 1073743378 Number of Bedrooms
  • 1073743379 Number of Bathrooms

• unit_configurations describes the bed type(s) in a room and how many of each bed type are in the room.

• house_rules is being deprecated. Please do not use.

• enhanced_house_rules:

  • May include a free text description provided by the host, which may include critical information to the guest's stay. additional_information can include information critical to the guest's stay such as policy clarifications and stay collected fees (city tourist taxes or usage-based charges).
  • Policy types returned include:
    • CheckIn
    • CheckOut
    • MinBookingAge
    • Occupancy
    • Events
    • Pets
    • Children
    • Smoking
    • CustomRules

• rental_agreement links to a PDF provided by the property manager which must be displayed on any check-out page. Please see launch requirements for more details.

• Descriptions: General

  • This is a machine generated description of the vacation rental property based on property attributes, amenities, and location. This text does not include any guidance or information the host. This field is most relevant to conventional lodging properties.

• Vacation_Rental_Details: free_text

  • This is a free text field provided by the host and includes the most information about the property which is relevant to a vacation rental shopper. It may include information about guest experiences available at or nearby the property, information about property amenities, additional amenities which may have additional charges, or information about the property or surroundings the guest should know about before booking (e.g. construction, noise, water conditions, ski slope access, parking, etc.). This section can be quite verbose, so careful attention should be paid to UI display of this field, particularly on mobile experiences.

Example:

"free_text": "Enjoy this beautiful seven level  home year round! This home is an expression of peace and love in every season. We have had many repeat guests. The home includes a beautiful hot tub outside, a gourmet kitchen and cozy breakfast nook. This house has internet access, so bring your computer with WiFi. The dinning area and living room, including the new deck outside are simply majestic; especially when viewing the ski area and skiers below! 

The upstairs features two beautiful master suites, with a sitting area and fireplace in each suite. The king suite has a double futon and the upper queen suite has a single futon. This upper queen suite connects from the bathroom to a smaller queen room with a double futon. There is one exit for these rooms (ideal for families!)

Downstairs there are two twin bedrooms with 2 twin beds in each room and a large bathroom with a tub/shower close by. The downstairs also  includes a relaxing entertainment center (on the same level as the outside hot tub), with a 60' flat screen TV!) wet bar and small pool/game table.

This level also has a queen and two single futons (yes, this home is perfect for large groups!). The huge new deck features ample seating and check out the chair lift seat! The views in every season are absolutely incredible! 

In the fall we have Balloon and Wine Festivals and Rugby Tournaments, among many other activities and summer welcomes a variety of Music Festivals in addition to gorgeous hikes, biking and shopping! The reservoir where the Mastodon discovery was found is now visible from the large front window during the summer! Also during the summer there is the Elk Camp gondola ride with dinner, playground in Snowmass, rock climbing wall, strider bikes, lawn games, nature hikes, gondola rides and activities and more. Many of these activities are free and perfect for children of all ages!

Snowmass Recreation Center at the base of the hill by the rodeo grounds includes a pool, basketball courts, weights, salt water hot tub. Call for updated information. 

The home is near the top of a steep winding road and not directly on the slope. This ski in/out home has many trails connected to the major ski runs and is only about 100 yards from the runs, which you may view from the rear deck of the house. The lift visible from the house is Coney Glade. 

The Wood Run Ski Trail, leading to the slopes is only about 120' from the house-2 houses down.*Some access trails to the lifts for ski in/ski out can be considered challenging relative to your personal skiing ability. Some are very easy. *During low snow pack you may need to take your skis off and walk*

To Ski Out From the House: 
Take the Wood Run Ski Trail. It is on your left at the end of Little Lane. This is the  more challenging trail. Or Walk/Ski (or have someone drive) 2/10 of a mile to the underpass and climb to the left side of the underpass (there is an embankment there.) This is Adams Ave. Take this run to the Village below. This is the easy way to ski out. Walking to this bridge below is about 200 yards.

To Ski In From the Ski Slope:
Take the Green Cabin run and near the lower portion of the run stay to the right. Look for the round 'target' sign. Take the 'cat walk' to Wood Road (it is 2/10 of a mile to the house.) Follow the trail down to the left (it parallels Wood Road) and follow this trail to the house. 

Gorgeous 4,500 sq. foot mountain vacation home  overlooking the ski slope. Stunning architecture, ski-in-ski out (short walk to trails), summer hiking and mountain biking, rodeo, unbelievable aspen and fall colors, music, dining and entertainment in both the upper and lower villages. The directions are available. It is a quick 5 minute drive (about a mile) down the hill to Clark's grocery store.

This home is perfect for large family gatherings and retreats as well as for a romantic 'getaway', and the unique design of the home ensures privacy on all levels.
There is a 2 car garage and parking spaces around the house for 6 vehicles."

• The following fields are only relevant to the Vrbo link-off model
  • vrbo_srp_id
  • listing_id
  • listing_number
  • listing_source
  • listing_unit

Shop and Availability

• Shop response considerations:
  • Vrbo properties are single room only at this time.
  • Same day bookings are not supported (no availability will be returned).
• Fields which may not be relevant to Vrbo inventory:
  • Room ID, Room Name, and Rate ID are not applicable to Vrbo inventory and should not be displayed.
  • Available rooms is always 0 for Vrbo properties.
  • Vrbo properties have only a single rate type as they are all single-unit at this time.
  • Bed groups and configuration are not applicable to Vrbo as no selection/preference is available.
  • Promo ID and description are not applicable to Vrbo inventory.
• Shop response new fields:
  • Property_Fee

Example:

{
"type": "property_fee",
"value": "34.75",
"currency": "USD"
}

• Please note that the Traveler Service Fee is non-refundable as soon as any part of the booking is non-refundable. Please see launch requirements for more information about display.

Example:

{
"type": "traveler_service_fee",
"value": "30.25",
"currency": "USD"
}

• Refundable Damage Deposit (RDD) is an amount charged to the customer card as part of the last scheduled payment. If the booking dates are imminent and 100% of rate is due immediately, RDD could be charged at the same time. RDD is then refunded approximately 10 days after the guest's departure assuming no property damage. RDDs are only charged for approximately 1% of Vrbo bookings.
  • Partners should display RDDs to the guest when a guest card is used for payment, otherwise RDDs should be filtered out when partner is paying with a virtual card.
  • Vrbo will send a summary of damages and invoice to the guest when damage claims are made.

Example:

"rates": [
    {
        "refundable_damage_deposit": {
            "value": "150.00",
            "currency": "USD"
        }  
    }
]

• A Card-on-File amount indicates that Vrbo has the right to charge the provided card after check-out if the guest causes property damage. Vrbo will send a summary of damages and invoice to the guest when damage claims are made. If the charge to the card provided with the booking fails, Vrbo will send communications to the guest requesting they submit payment via the Vrbo site.

Example:

"rates": [
    {
        "card_on_file_limit": {
            "value": "500.00",
            "currency": "USD"
        }
    }
]

• Deposit policies, when present, should be clearly communicated to the guest if the guest's card is used with the booking. Vrbo will send an email reminder to the guest to sign into Vrbo to complete payment. If payment is not made the booking may be canceled.

Example:

"deposits": {
    "value": "500.00",
    "due": "500.00",
    "currency": "USD"
    },
   {
    "value": "500.00",
    "due": "500.00",
    "currency": "USD"
   }

Book

• You must provide guest contact details (name, phone, and email) with each booking to facilitate host-guest communication.
• Vrbo has stricter requirements for which countries need state and postal codes with a booking. More details in Appendix 3 below.
• Rental agreements, when provided in content, must be displayed on the check-out page. Please see launch requirements for more information.
• Cross border payments:
  • Vrbo is required to collect VAT on the Traveler Service Fee portion of each transaction. This requirement is driven by the location of the guest, as determined by the billing address. As a result, in order to enable a successful booking the shop price must reflect the billing address country. If there is a mismatch a pricing error may occur.
  • Partners should ensure they shop with the correct country, or if they detect a different country input by the guest, they should re-shop for an updated price.

Partner Merchant of Record

Vrbo supply requires a valid credit card for payment, Expedia Affiliate Collect is not supported at this time. However, bookings which have a payment schedule require a guest credit card as the guest will receive a reminder from Vrbo to access their Vrbo account and make the scheduled payment prior to the due date. Partners who cannot provide the guest credit card may pass a virtual card when 100% of the booking is charged to the card at time of book.

Merchant Eligibility

Eligibility for MOR=Expedia is dependent on two criteria:

• Properties with a payment schedule are not eligible for merchant treatment. Most properties booked within 30 days do not have a payment schedule, while ~25% of properties booked further out may have a payment schedule and thus MOR=Property.
• Properties where the payment from the guest differs from payout to the property are not eligible for merchant treatment. This includes cross-border bookings where currencies differ.

How to identify eligible properties?

In the Rapid shop response eligible properties may have either of the following identifiers:

• merchant_of_record=expedia These properties are single payment and can be canceled via the Rapid API.
• deposit_policy section does not exist or the section describes a single payment taken at time of book.

Conversely, properties with the following are ineligible and prior to the scheduled payment due date Vrbo will send the guest a payment reminder.

• merchant_of_record=property and deposit_policy describes multiple payments.

How are damages handled when the partner is Merchant of Record?

Properties with Refundable Damage Deposits (RDDs) - Partners should filter out search results which describe an RDD. This is only 1-2% of properties.

• In order to filter out Vrbo shop results which have a refundable damage deposit, include the following Rapid Shop parameter: exclusion=refundable_damage_deposit

Properties with Card-on-File - Vrbo will attempt to charge the card provided with the booking in case of damages, up to the amount specified in the shop and itinerary Card-on-File section.

• Guest card - Partners should inform guests that they will receive a charge to their card if they damage the property, up to the specified amount.
• Partner card - If the partner virtual card is closed, partners should inform guests that they will be responsible for damages, up to the specified amount, and Vrbo will reach out to them for payment. If the partner virtual card is open, partners are responsible for collection of damages from the guest.

Post-Book

• Some Rapid itinerary fields and tokens may not be available or may not apply to Vrbo bookings:
  • Cancel refund amount may not be accurate
  • Cancel token (provided for merchant bookings, not for property collect)
  • Conversation token
  • Soft change
  • Hard change
• The Vrbo confirmation number (HA-########) should be provided to guests as it is the only reference available to the host and Vrbo support, and is referenced within any Vrbo emails.
• Vrbo bookings can be canceled as follows:
  • Guest or partner agent via Traveler Partner Service Platform (TPSP)/Vrbo support.
  • Guest or partner email to the host.
  • Respond to host welcome email.
  • Initiate request using email provided in Rapid Itinerary Essential Stay Content.
  • Rapid Cancel API when booking is eligible (merchant_of_record must be Expedia to cancel via Rapid API).
  • If Vrbo was unable to confirm cancellation of the booking, a request will be raised to the property host to complete the booking cancellation and process the refund.
• Booking changes
  • Vrbo bookings are not eligible for modification via the Rapid API. Instead, partner agents or the guest should contact TPSP, who will loop in a Vrbo agent to support any change requests. A separate booking may be preferred/required.

Essential Stay Details

Rapid Essential Stay Details can be used to supplement, and eventually replace, the Vrbo Welcome Guide email. At this time Vrbo will still send their Welcome Guide email to the guest, but we will suppress this communication in the future.

Additional details including a list of possible essentials can be found here.

Expand All

|

Collapse All

Appendix 1: Host Communications

All Vrbo bookings are required to include the customer email to facilitate direct communication between the property manager and the traveler. Use of a partner/agent email risks booking cancellation by the host in some cases.

Examples of property manager communications include:

• Welcome message and introduction to the property manager
• Contact details
• Policies and Know Before You Go
• Address and directions
• Key box code
• Payment schedule
• Rental agreement (may be required or property manager could cancel booking)
• Passport photo request (may be required or property manager could cancel booking)
• Cancel confirmation
• Refund confirmation

Example:

Appendix 2: Vrbo Communications

Vrbo will also send a confirmation email to the email address provided with the booking. These emails cannot be disabled at this time.

Common Vrbo email templates:

• Booking confirmation
• Booking canceled by traveler
• Booking canceled by property
• Fraud cancel
• Damage deposit charged
• Damage deposit receipt
• Damage deposit claimed
• Scheduled payment overdue
• Payment received
• Payment refund
• Traveler requests cancel
• Host responds to message
• Welcome guide
• Re-marketing (US only)
• Property review request
• Support experience review request
• Duplicate booking

Vrbo.com guest interaction-based email templates:

• Traveler messages host
• Account creation
• Password reset
• Password reset confirmation
• Password creation
• Guest invite
• Guest invite follow-up
• Additional payment request
• Payment request
• Payment reversed
• Offline payment sent
• Offline payment received
• Payment confirmation
• Payment cancel requested
• Payment canceled
• Booking updated
• Booking change accepted, no payment
• Booking change requested
• VAT purchase receipt

Vrbo.com booking management capabilities include:

• View/download invoice/VAT receipt
• Contact property manager (messaging)
• Request cancellation
• Check-in/out times
• Property manager name
• Charge summary
• Payment schedule
• Insurance offer

Appendix 3: Postal Codes and States

Billing Address Requirements for Invoicing

Vrbo bookings made via the Rapid API have different zip/postal code and state requirements at this time. Please refer to the table below for requirements for your point of sale.

See below for details:

Countries with Postal Codes	Countries without Postal Codes	Countries with Postal Codes and Additional Details
Afghanistan	Angola	Australia: State
Åland Islands	Antigua and Barbuda	Brazil: State (+Neighborhood on BR POSA) and CPF/CNPJ
Albania	Aruba	Canada: Province
American Samoa	Bahamas	Japan: State and Address line 2
Andorra	Belize	Spain: National ID
Anguilla	Benin	United States: State
Antarctica	Botswana
Argentina	Burkina Faso
Armenia	Burundi
Austria	Cameroon
Azerbaijan	Central African Republic
Bahrain	Comoros
Bangladesh	Congo
Barbados	Congo, the Democratic Republic of the
Belarus	Cook Islands
Belgium	Côte d'Ivoire
Bermuda	Djibouti
Bhutan	Dominica
Bolivia, Plurinational State of†	Equatorial Guinea
Bosnia and Herzegovina	Eritrea
Bouvet Island	Fiji
British Indian Ocean Territory	French Southern Territories
Brunei Darussalam	Gambia
Bulgaria	Ghana
Cambodia	Grenada
Cape Verde	Guinea
Cayman Islands	Guyana
Chad	Hong Kong
Chile	Ireland††
China	Kenya
Christmas Island	Kiribati
Cocos (Keeling) Islands	Macao
Colombia	Malawi
Costa Rica	Mali
Croatia	Mauritania
Cuba	Mauritius
Cyprus	Montserrat
Czech Republic	Nauru
Denmark	Niue
Dominican Republic	Panama
Ecuador	Qatar
Egypt	Rwanda
El Salvador	Saint Kitts and Nevis
Estonia	Saint Lucia
Ethiopia	Sao Tome and Principe
Falkland Islands (Malvinas)	Seychelles
Faroe Islands	Sierra Leone
Finland	Solomon Islands
France	Somalia††
French Guiana	South Africa††
French Polynesia	Suriname
Gabon	Syrian Arab Republic
Georgia	Tanzania, United Republic of
Germany	Timor-Leste
Gibraltar	Tokelau
Greece	Tonga
Greenland	Trinidad and Tobago
Guadeloupe	Tuvalu
Guam	Uganda
Guatemala	United Arab Emirates
Guinea-Bissau	Vanuatu
Haiti	Yemen
Heard and McDonald Islands†	Zimbabwe
Holy See (Vatican City State)
Honduras
Hungary
Iceland
India
Indonesia
Iran, Islamic Republic of
Iraq
Israel
Italy
Jamaica
Jordan
Kazakhstan
Korea, Republic of
Kuwait
Kyrgyzstan
Lao People's Democratic Republic
Latvia
Lebanon
Lesotho
Liberia
Libya†
Liechtenstein
Lithuania
Luxembourg
Macedonia, the former Yugoslav Republic of
Madagascar
Malaysia
Maldives
Malta
Marshall Islands
Martinique
Mayotte
Mexico
Micronesia, Federated States of
Moldova, Republic of
Monaco
Mongolia
Montenegro
Morocco
Mozambique
Myanmar
Namibia
Nepal
Netherlands
New Caledonia
New Zealand
Nicaragua
Niger
Norfolk Island
Northern Mariana Islands
Norway
Oman
Palau
Palestine, State of
Papua New Guinea
Paraguay
Peru
Philippines
Pitcairn
Poland
Portugal
Puerto Rico
Réunion
Romania
Russian Federation
Saint Barthélemy
Saint Helena, Ascension and Tristan da Cunha
Saint Pierre and Miquelon
Saint Vincent and the Grenadines
Samoa
San Marino
Senegal
Serbia
Serbia and Montenegro
Singapore
Slovakia
Slovenia
South Georgia and the South Sandwich Islands
Sri Lanka
Sudan
Svalbard and Jan Mayen
Swaziland
Sweden
Switzerland
Taiwan, Province of China
Tajikistan
Thailand
Togo†
Tunisia
Turkey
Turkmenistan
Turks and Caicos Islands
Ukraine
United Kingdom
United States Minor Outlying Islands
Uruguay
Uzbekistan
Venezuela, Bolivarian Republic of
Viet Nam
Virgin Islands, British
Virgin Islands, U.S.
Wallis and Futuna
Western Sahara
Zambia

†Countries with partial availability of zip/postal codes but maintained as mandatory on Vrbo checkout.

††Countries with partial availability of zip/postal codes but that we don't have as mandatory.