Getting started with TourCMS API, part two (for Agents)

Blanca Castillo
Blanca Castillo
  • Updated

Make sure you have read part one.

Connecting to TourCMS to load your own tours & activities to sell? Read part two for Operators instead.

Common use-cases

If you are importing TourCMS products into your own database you will likely use List Tours to obtain a list of tours you can access, Show Tour to get the descriptions and images plus the rate types required for booking. Tour Departures will give you a list of all Departures for that product, including a detailed pricing breakdown for each rate on each date. Alternatively if you only wish to know which dates are available, Dates & Deals is faster.

If you are using TourCMS API to directly power the descriptions on your website you will likely use Search Tours to display listing pages, Show Tour for detail pages, Dates & Deals for an availability calendar. Alternatively consider adding Widgets to your page.

To place bookings in TourCMS please see the endpoints in our booking creation documentation. Alternatively there is a hosted booking solution which can be easily added to your website in a few moments.

Uniqueness within TourCMS

Unique product IDs

There are 3 core IDs that you will see returned in the data:

  • Account ID - This is unique per TourCMS account. A single account can have multiple channels (each channel perhaps featuring different products, different language but same products or different prices but same products)

  • Tour ID - Unique per Account ID but will be non-unique over multiple accounts

  • Channel ID - Unique per channel

Hence if you care about removing duplicate tours, filter by a combination of Account ID / Tour ID.

You can filter by combination of Channel ID / Tour ID however if you are connected to the same TourCMS supplier account over multiple of their sales channels, you could have duplicate tours (e.g. an English version plus a French version)

To tell if it is the same tour from the same tour operator supplier, just in a different sales channel (e.g. perhaps with a different description language), check Account ID / Tour ID combination

Unique booking / customer IDs

There are 3 core IDs that you will see returned in the data:

  • Account ID - This is unique per TourCMS account

  • Customer ID - Unique per Account ID but will be non-unique over multiple accounts

  • Booking ID - Unique per Account ID but will be non-unique over multiple accounts

Permissions

Permissions are set by the TourCMS account owner. All agents can see dates, prices, availability & create new bookings (via API and booking engine) and create enquiries (via API)

 

Level

 

Description

 

1 - Sell only

For advertisers

  • See products, dates, prices & availability

  • See clicks

  • Create enquiries (Via API)

  • Create bookings (Via API and via booking engine)

Generally used when a tour operator/supplier wants someone to promote their product but if they are paying an annual listing fee (rather than on a success basis) they don't want to disclose how successful the advertising has been.

2 - Summary statistics

For agents/affiliates (DEFAULT)

  • See basic booking / customer information - Lead customer name, travel dates, sale value & commission (if set)

  • See own enquiries

  • .... and also all actions that 1 can do

Designed where you don't want to over disclose customer personal information e.g. with an affiliate who only referred you web traffic (that subsequently turned into a booking) rather than an actual customer booking

3 - Full detail

For travel agents

  • See name, address, full details for all customers on the booking

  • See list of payments

  • See customer special requests

  • See customer travel insurance details

  • See booking summary (e.g. the same as %summary_sale_table%)

  • .... and also all actions that 1 and 2 can do

You can disclose the customer information to the agent at this permission level as the chances are they gave you the booking in the first place hence already have that information.

Agents will will NOT see profit margin, costs or which suppliers have been used.
 
 
 

 

i.e. Generally affiliates/marketing partners can see and sell product. Traditional Travel Agents can see bookings/enquiries.
Tour operators can see and alter customer / booking data

Seeing no data

  • You can only see data from TourCMS accounts you are connected to. The onus is on the TourCMS account to give permission for you to see their data (perhaps after a commercial conversation)

  • The API will normally only return data from TourCMS accounts that are paying (i.e. not free trial accounts) and are in good standing

Testing

  • Inside the Marketplace agent login is a test harness to easily review responses to various XML calls

  • The Marketplace agent login also has an API log so you can review recently made API requests and their responses as well as failure reasons

Product prices

The majority of API calls give you RETAIL (sale) prices. These can be shown directly to consumers

If you (as a travel agent) are working on commission OR net rates, the RETAIL prices will carry through the booking howevery your BALANCE OWING will take into account your commission or your agreed net rate. i.e. you will pay less than the retail price at point of paying

If you want to know what the net rates will be ahead of time, they can be found via the Show Tour Departures API call.

If you are working with some suppliers on commission and some on net rates, TourCMS will work this out for you automatically

API checklist

TourCMS do NOT mandate that we ratify or check your API integration - however - for some larger projects we do. This is what we will check

 

1

Commercially sensitive data
Net rates (i.e. commercial rates sold by a supplier and given to a travel agent) should never be exposed to customers
Likewise, suppliers will give you average transaction size, click to book ratio etc. This should not be exposed to customers either

2

Quality control
All tours in the TourCMS API have a minimum amount of data completed; so you can be sure products have base descriptions, geolocation, at least one image etc.
 
Additional quality control is available to allow agents/affiliate to only feature tours that meet or exceed our Content Quality Guidelines including large image sizes and improved descriptions.
 
Quality control can be used on a per API request basis, however we would recommend agents/affiliates switch on quality control inside their TourCMS control panel, ensuring quality control is in place automatically wherever available.

3

Hotel pickup points
Ensure that hotel pickups are added at point of booking. It is possible to create bookings without hotel pickups but generally hotel pickup selection should be shown and handled.

UI design notes
Hotel pickups can be time sensitive - e.g. a hotel may be on a route for a morning tour but not an afternoon tour. This is why pickups are on the check availability API

You know the time of the pickup (e.g. 10:00 or 14:00) - don't let the customer pick the 14:00 for a 11:00 tour start time

Some tours have freetext "on request" hotel pickup capabilities. Check if this needs to be supported in your UI.

4

Display the date "note"
Particularly when offering clients the ability to choose between various components available on a certain date the start/end date, start/end time is NOT sufficient to distinguish between all trips. The "note" can often be vital (e.g. could be zone information for a transfer, or a specific language that the tour is being run in).
 
User interfaces for selecting between the available components should at a minimum show dates, times and "note" field where they differ between the components returned.

5

Total sale price may not be total of all the components
There can be booking fees. There can be discounts for adding multiple components to the same basket. Check the value that comes back from booking start - rather than adding individual component sale prices.

6

Airport transfer information collected
For product type 2 - Transport/Transfer - please collect the following information:

Mandatory (most of the time!)
Airline/Train name
Flight/Train number
Arrival Time
Hotel name

Consider adding
Origin
Destination
Hotel address
Greeting board details
Luggage (e.g. Skis)

This should be sent through in the note, on the component, in booking_start as follows:

Airline : ABCDEF Flight : GHIJKL

7

Total customers
Ensure that the correct total_customers is sent to booking start. If you don't know how many total customers you have, if you have a booking including one tour with 4 people & another tour with 3 people our general advice is to send 4 not 7 as the total_customers number.

8

API caching
If calling the API in live time - that - as far as possible - API requests for tour search, details & dates/prices are cached (e.g. for 10 minutes). (Booking should always be done on live API calls though). Further information on caching

9

Agent reference
On booking start and IF you are making a booking in a 3rd party system outside of TourCMS, please send the 3rd party system booking reference to TourCMS as agent_ref. Additionally, it is helpful if you preceed with your service name e.g. GLOBALOTA-123456. Define your service name as you like (we know the booking was made by you via other tracking). You MAY just have a booking reference, no service name, but it is preferable to have a service name. This agent reference, apart from being used for vouchers (see below) is helpful to tour operators to manually reconcile bookings between your system and TourCMS, if necessary

IF you are only making the booking in TourCMS (and not your own system simultaneously) you may leave agent_ref blank

10

Voucher bar codes
Please read and ensure you implement our guidance on vouchers and barcodes.

11

Your own email notifications (to supplier)
If you are an Online Travel Agent (OTA), you send email notifications to the supplier (TourCMS powered tour operator) telling them about their new booking. Unless otherwise agreed with the supplier, please continue to send your email notifications even if you are also sending the booking via our TourCMS API (Many will ask you to turns your email notifications off, but best to wait for them to tell you, rather than assuming). The email address to send to is email_customer from Show Channel.

12

Defaulting next bookable date on a single tour page
On a single tour page, when you are showing an available date calendar (probably informed by Dates & Deals)), default the next bookable date to next_bookable_date from Show Tour API rather than the first date in the dates & deals API.

The next bookable date from tour show updates quicker than the dates & deals API (which is heavily cached), so this will be a more accurate approach

13

Supplier sign off to go live
YOU MUST contact any supplier before you turn on for bookings and wait for their sign off / agreement to go live

Specifically, please do not go live on a Friday.