Viator Merchant API Certification

1. Please do not attempt to ingest the full content of products with each ingestion run. You should ingest the full product catalogue once, and then ingest only updates (this reduces load on our systems and theirs and improves ingestion time for the partner) with the /products/modified-since endpoint. The more frequently this endpoint is called, the better as this way less data will be returned and the update will be much faster.
   The /products/{product-code} and /products/bulk/ endpoints should not be used for ingesting and updating the product catalogue unless you are ingesting products that haven’t been ingested before (for example, due to additional filtering rules on your end). The relevant endpoint serving this purpose is /products/modified-since.
2. If you are an ingestion partner (storing our content in your local database), please ensure that tags and booking questions are cached. We suggest a periodic weekly update, unless a new tag or booking question is detected in the product content.

1. Similar to product ingestion, please ingest schedules for all products once and update from there on with the /availability/schedules/modified-since endpoint. The more frequently this endpoint is called, the better as this way less data will be returned and the update will be much faster.
2. You should never use the availability real-time request ( /availability/check ) for ingestion purposes.
3. If you are converting prices from our supplier currency into your desired currency using the exchange rate endpoints, you should call the exchange rate once per day based on the expiry timestamp to determine the rate and apply to all products priced in that currency (this greatly reduces the number of calls to our system).

1. You must check availability real-time (along with pricing) even if you have already ingested availability schedules. This is because the availability or price you ingest may become stale immediately after you ingest it (i.e. our supplier makes product unavailable or changes the price in the system after the ingestion took place).
2. You must verify availability (real time) of a bookable item/ passenger-mix/travel date combination before a booking or booking hold request is made for that same bookable item / pax-mix / travel date. This is irrespective of the booking engine. a bookable item is what a customer actually purchases (i.e. the product or the product option or the start time – whichever is the lowest level on the product).
3. Availability (real-time) requests should only be made when the customer has selected a date, passenger-mix and one of the following combinations:
   1. a product – returns availability for the product or production options and/or start times
   2. a product and a start time – returns availability for the product start time
   3. a product and an option – returns availability for the product option or the product option start times
   4. a product, an option and a start time – returns availability for the product option start time.

Each of the above serves a specific purpose in the UI. For example, if you want to list availability for all of the options and start times of any product, you would call availability for the product only which returns availability and pricing for all its options and start times. If you just want to check that a product start time the customer is booking is available, you would call availability using the product and start time as parameters. Using the right request for the right scenario is important to keep processing fast.

The request to /availability/check endpoint should be made with the currency in which you wish to be invoiced by Viator. This way you will be able to verify the final rate in that specific currency and avoid possible pricing discrepancies that could occur due to exchange rate fluctuations. This is especially important if you decided not to use the /exchange-rates endpoint.

• This endpoint holds price and inventory for x amount of time. x is defined by our supplier for inventory, and standard across all products for price.
• This endpoint must only be called when there is strong intention from your customer to purchase. This means that it should be called immediately prior to the credit card payments being requested from the customer. This has two benefits:
  • it ensures the customer has time to enter details of the card without the risk of the inventory being sold out or the price changing.
  • it ensures that inventory is only held when there is a strong likelihood of a purchase, therefore not holding inventory that may otherwise be sold to someone else.
• Booking hold must not ever be used for checking availability. It should be done after availability and pricing is verified in real-time with /availability/check endpoint.
• Partner is responsible for verifying the timestamp returned under the validUntil field for pricing and availability in the response to /bookings/hold to ensure that the booking is made within the time of hold. A new hold can be placed only in case the previous hold expires.

1. Booking Status should not be called more than once every 3 minutes, if partner supports manual confirmation products.

1. When getting details of location references with /locations/bulk, please make sure to use no more than 500 location references in each request.
   Locations should be updated only on an on-demand basis, when a new location reference is returned in the product content response.

1. Your entire tours and activities platform is recommended to have a valid HTTPS security certificate.

• /availability/schedules/modified-since
• /availability/schedules/bulk
• /availability/schedules/{product-code}

Continue to make requests with the cursor parameter set to the value of the nextCursor element returned by the previous request. Eventually, a request will return no data in the products element, and will not include a nextCursor value. This indicates that all products have been returned. To optimize ingestion time, we recommend setting the count parameter to it’s maximum value of 500 for each request.

To periodically refresh your database, repeat steps one and two in a regular cadence.

1. Schedule each product and availability ingestion cycle for one hour after the previous cycle has been completed.

2. If you would like to exclude certain products or product types, you can do so at the time of ingestion. When ingesting products, assess whether the product contains undesired attributes and discard the product (do not store it).

3. You should only ingest schedules for the products you have ingested – that is, if you have excluded products from the product ingestion, you should not ingest the availability schedules for those products. You can filter on ingestion by discarding information for products you are not interested in.

Locate the cancellationPolicy object in the response from any of the product content endpoints.

1. Display cancellation policy in writing on the product detail page and on the checkout page.

Using the minTravelersPerBooking and maxTravelersPerBooking fields as reference, set upper and lower bounds on the total number of travelers your users may input when booking this product. The total number of travelers refers to the total number of travelers across all ageBands.

1. Communicate the maximum and minimum travelers to the user. For example: “This experience is bookable by 2-15 travelers.”

2. If an adult or senior traveler is required, communicate this to the user. For example: “At least one adult or senior per party.”

3. Do not include the option to select invalid passenger mixes. From a UX perspective, preventing your users from selecting invalid mixes at all is preferable to displaying error messages.

1. Avoid excluding products with specific age bands, as this will significantly limit your available inventory.

2. Collect age bands on the product detail page, just before displaying tour options.

Locate the bookableItems.seasons.pricingRecords.timedEntries array in the response from any of the availability schedules endpoints. This array will include all data on start times and availability for a product; or, if available, its product options.

Determine the bookable item(s) for the product, and collect one of the following combinations (a bookable item):

1. The product code (productCode)
2. The product code, and the user’s desired start time (productCode and startTime)
3. The product code, and the user’s desired product option (productCode and productOptionCode)
4. The product code, the user’s desired valid start time, and the user’s desired product option (productCode, startTime, and productOptionCode)

Each of the above combinations serves a specific purpose in the UI. For example, if you would like to list the availability of all product options and start times for a product, you would only include the productCode. If you just need to check whether the start time requested by the customer is available, you should include productCode and startTime. To keep processing fast, it is important to choose the right request for each scenario.

1. In general, the real-time availability check should be made immediately prior to presenting the user with the option to purchase the item. This minimizes the possibility that the customer will attempt to proceed to the payment page only to find that the bookable item is no longer available.

1. If possible on your platform, collect the booker’s information at checkout, rather than earlier on in the user journey.

Make a request to the /products/booking-questions endpoint. The response will contain a flat list of all booking questions, including each question’s machine-readable identifier, plain text for display to the user, and parameters for acceptable answers. This data is mostly static and may be stored locally, but we recommend it be refreshed weekly; or ad hoc if an unknown booking question is encountered.

1. Do not exclude products with booking questions, as this practice will significantly limit your available inventory and revenue opportunity.

Note: The locations array will include location references, which must be resolved before they are displayed to the user. For guidance on working with location references, please refer to our documentation.

If the logistics.travelerPickup.allowCustomTravelerPickup boolean in the product data is true, the user may specify their own pickup point. This should be displayed as an additional option, which, if selected, will allow the user to input their own freetext answer.

Select a product to book. You may refer to the above list of products, or any select Viator product with availability.

Make a /bookings/book request. The request body for this request must include the same parameters as the request body of the appropriate /bookings/hold request, otherwise the booking will be rejected. The request body of all booking requests must must include the Viator booking reference returned by the /bookings/hold request (bookingRef), a partner-generated reference number for internal use (partnerBookingRef), the first and last name of the person making the booking (bookerInfo object), and the contact info of the person making the booking (communication.phone, optionally communication.email).

In addition, the following objects may be required, depending on the product in question: languageGuide, bookingQuestionAnswers, and optionally additionalBookingDetails.

Make a valid booking using the /bookings/book endpoint. When making your request, you may customize some textual elements of the voucher via the fields in the voucherDetails object of the request body.

Note: You may choose to include the logo of your organization on vouchers. This is managed by Viator at the account level, so please contact our API onboarding team for assistance with this feature.

1. The traveler should be able to access their voucher(s) through the booking confirmation email sent by the partner, or when they log in to their account.
2. Accepted voucher types should be indicated on the product detail page.

Select a product with future availability, and with Viators standard cancellation policy.

Using your production API key, make a valid booking using the /bookings/book endpoint. Be sure to select a date more than 24 hours in the future.

Note: When working in the production environment, https://api.viator.com/partner/… should replace https://api.sandbox.viator.com/partner/… for all endpoints.

Using the /bookings/{booking-reference}/cancel endpoint, cancel the booking.

Share the booking reference for the cancelled booking with our onboarding team. Viator will confirm that booking data is correctly remitted to your invoice, and will reply with approval to launch (if booking data is correctly remitted), or next steps (if an error is detected).