Connectivity overview for non-technical project participants

This section provides information for project participants that are focused on the operations side of the business to understand the information the API connection will provide and how that relates to procedures normally carried out using the management center.

API overview

The API comprises two sections:

Availability and pricing APIs

The availability and pricing APIs include:

These three APIs help to reduce the manual maintenance work that is currently undertaken in the management center. It is mandatory to support the batch availability and real-time availability APIs.

Product availability is managed by the following APIs:

1. Batch availability API

This API updates the data used by the calendar that shows product availability on our sites. It can be used to automate the process of blocking-out dates on which the product is unavailable that would ordinarily be accomplished using the Availability section of the management center.

If you need to modify the availability of a product on a certain date, this change needs to be carried out on your system. Your changes will appear on our calendars once the periodic update occurs. The frequency of the update depends on how far in the future the affected date is, as follows:

Days into the future Calendar update frequency
0-2 2 hours
3-30 1.5 days
90 3 days
180 4.5 days
180+ 7 days

Therefore, please allow enough time for changes to availability made on your system to be picked up and reflected on the Viator and Tripadvisor calendars.

2. Real-time availability and pricing API

The real-time availability and pricing API checks that the date is still available before allowing a customer to proceed with their booking. If a customer selects a date that is no longer available, your API will respond with an unavailable message (e.g.: 'sold out' or 'no event'). The customer will be prevented from proceeding with the booking and will be asked to select an alternative date.

This API also checks the group size; for example, if we receive an availability request for three adults, and you only have two places available, an unavailability reason of “traveller mismatch” will prevent the booking of three, but it will not block the date from sale. We encourage internal discussion about the differences in the availability responses for the date and the traveller mix.

The Pricing section of the real-time availability and pricing API returns the per-person price for each traveller in the booking. The price received in this response is shown to the customer before they proceed with their booking. If you also return AvailabilityHold, we expect the price - as well as the inventory - to be held. The introduction of pricing information in the real-time availability response is to provide you with the flexibility to be more dynamic with your pricing.

Lastly, the real-time availability and pricing API provides you with the flexibility to reduce your booking cut-off time. We will always make an availability check and only send the booking to you if we receive an 'available' response.

3. Batch pricing API

The batch pricing API is currently in beta. If you are interested in supporting this API, please initiate a discussion with your API account manager before starting development so that we can assess whether your system can support it.

This API is similar to the batch availability API. Its role is to bulk-update the pricing as shown on the schedule and prices tab in the management center. On our shop front, the lowest price available for a date is used as the “from” price. This price is also used if the real-time availability and pricing API fails for any reason. As pricing changes less often than availability, this call runs less frequently when compared to the batch availability API.

When batch pricing is enabled, your team will no longer need to update pricing manually in the management center, as all pricing information will be copied over automatically from your system. We have included a screenshot below of how the management center will appear once batch pricing is enabled.

Figure 1

Note that when the batch pricing API is supported, you must also include the pricing information in your response to the real-time availability and pricing API. Together, these 2 APIs ensure we always receive the most up-to-date prices from you.

Batch pricing and the minimum margin

You have a few options regarding the price that you return in the batch pricing API response, depending on the price that is set in your system.

Your options are to:

  1. Return the net rate only (we will then add the margin). This is the preferred option.
  2. Return the retail rate only (we will then subtract the margin).
  3. Return both the net and retail rate. In this situation, no calculations will be made. However, we will be alerted if the difference between the net and retail rate does not match our margin expectations.

Exceptions:

Pricing in our APIs is always based on the per-person rate, and this includes the batch pricing API. At present, we are unable to support tiered pricing or per-unit pricing (e.g., per car, boat etc.).

Our Batch Pricing API can only accept 1 currency and this should be the currency that appears in your management center. See available currencies.

Booking operations APIs

The booking operations APIs available to you are:

These four APIs ensure that bookings are processed correctly according to your system's protocols. Supporting these APIs, except for the booking amendment API, is mandatory.

Tour list

This API is used to retrieve the product codes (mapping identifiers) that identify your products on your system. This ensures that our product codes align with the correct product on your side and that any additional information - such as tour guide languages and departure times - are also synchronized.

You will see the information from this API when you click the Connect button in the Product Connection tab in the management center, and then selecting “Select it from their list of live products”.

Figure 1

The tour list will present all of the products that are available.

Once you select a product, our systems reach out to your batch availability API endpoint for at least one available date. This is to ensure that the product does appear in the batch availability response; and that, by entering the mapping, we will not inadvertently block a product from sale. Once you click “Save”, the product will be live and any new bookings will be sent directly to your system.

You can revisit this page at any time to check if the mapping values are correct; or, to re-map a product if you make any changes to it on your reservation system.

If a product does not appear in this list, please ask your development team if the product has been added to the tour list and batch availability responses.

Booking

This is the easiest API to understand, as it takes place at the completion of the booking process. This is when the booking is sent to your system. Once the API connection is live, you will no longer receive booking notifications by email unless the fallback process is activated.

Common questions regarding the booking information that is sent:

Q: Will I receive the customers direct email address?

No, due to company policy, we will never provide the customer's real email address. However, you have the option to have the same obfuscated email address that is currently hidden behind our “Contact Customer” button in the management center to be sent to you.

This is an optional feature that your developers can accommodate, and it will place the obfuscated email address directly into your reservation system so your reservations team does not need to log into our management center to send the customer an email.

The added benefit is that communication between you and the customer is logged in the booking history notes, should you need it for future reference. This email address is valid for 30 days after the travel date.

Q: Will I receive the customers direct phone number?

Yes, if the customer completes the phone number field on our checkout page, tit will be included in the booking information. Note, however, that not all partners support this field.

Q: Will I receive the customer's hotel information?

Yes, if you currently have the hotel pick up box activated for your products, the customer will be able to select their hotel from the drop down menu and this information will be sent to you in the “Pick up point” field.

If you are currently collecting this information from the special requirements field, the “Special Requirements” field will be populated with this information.

Q: Will I still receive the information that a customer enters during the booking process such as flight and cruise ship information?

Yes, this information is passed in the question and answer fields of the booking request.

Booking Cancellation

When a customer submits a cancellation request, this can be automatically sent to your system as an alternative to having your reservations team processing cancellation requests by email. This can reduce your administrative burden, ensures your availability is up to date, and provides you with an opportunity to re-sell the tickets.

Booking Amendment

Booking amendments are for any changes that need to be made to the booking details post-booking, but pre-travel. This allows the customer to hold the same booking number for the duration of the booking.

The changes that can be made include:

This API can update the booking details or notify your team of a change depending upon how you have implemented it on your side.

Considerations for a smooth connection

The Relationship between 'start times' and the API

Our management center provides you with different time options to accommodate different product types, such as opening hours and start times.

Figure 1

However, for the API connection, if the starting time that the customer selects is important for you to know in the booking details; or, if there is an inventory concern, you must return the TourDepartureTime tag as a mapping value and do not include the start time as part of the SupplierOptionCode.

In the management center, you will then be restricted to using only the 'start times' option. The reason for this that the starting time information in the management center synchronizes with the information in the TourDepartureTime field, and this information is then presented to the customer on our site.

Example of start times syncing on the product connection tab:

Figure 1

This appears to the customer as:

Figure 1

All starting times listed on the product connection page that have been synchronized will be displayed to the customer. If a particular starting time is not available, that time will appear crossed-out.

The benefits of using the TourDepartureTime tag include:

Eliminating the need to identify each start time as a product option

Note: If there are any changes made to the Time option in the management center; for example, changing from start times to opening hours, this will break the API connection unless the TourDepartureTime is also removed from the API response.

How to correctly handle the product's guide language when it is an inventory concern

If we need to check the availability for a specific operating language, then it is recommended to have 'language' as its own key/value pair. At this time, the guide language is still supported with product options on the schedule and prices tab; and, for this reason, we need to connect (map) each product option to the right language.

If you offer audio language guides and there is no inventory concern, then language is not required to be a mapping value. The audio guide language that the customer selects on the checkout page will be sent to you in the booking request.

When to use SupplierOptionCode and how this affects the product set-up

The SupplierOptionCode is used to differentiate between product options. For example, a dinner cruise may have two options: 'window seat' and 'best available'. The SupplierOptionCode is an easy way to identify the option being booked.

Figure 1

Should I support barcode numbers or pass-through tickets?

To decide upon the best option, we suggest considering how the customer will check-in or participate in the tour or activity.

For example, if the customer is happy to present our standard voucher (with the addition of the barcode number from your system) this can be achieved with either a per-traveller barcode (TravellerBarcode) or a per-booking barcode (TourBarcode). You can control the barcode type and the redemption information on the Tickets tab in the management center.

If the Tickets tab does not provide enough detail for the customer, you should consider supporting the TourTicket option. This option allows you to respond to our booking request with a URL to the PDF that the customer needs to present. The workflow is slightly different in this case, as the Viator / Tripadvisor ticket will be suppressed, and the customer will only see and receive your PDF. This option can not be controlled in the management center – please ask us to set this up for you if you wish to support this workflow.

Testing and how to go live

Once all of the considerations listed above have been addressed, development can proceed, and all APIs will be tested. We will check with you that any test bookings are received correctly and cancelled or amended as applicable. Once we all agree that testing is working successfully, then we can go live.

This process will include changing the API key used in testing to a production API key and selecting a pilot product. We recommend a product that will sell within a few days, but not your best-selling product.

If you are migrating from one system to another, products may need to be remapped, and this should be considered before moving into production.

The fallback process: what happens when the API fails to connect?

If an error is received; or, we are unable to validate your response, we will apply the booking process that appears in the management center.

Figure 1

This will allow customers to proceed with their bookings; therefore, you won’t lose any.

When errors do occur, API calls are still made; i.e., we will still make an availability call and a booking call. However, the responses to these calls will be what determines if the booking is made via the API or sent to you by email. Once the error is resolved, the API transactions will recommence.