home > support > API > webhooks > Check tour availability

Check Tour Availability Webhook

Notes

Called when a request is made to the Check Tour Availability API. TourCMS will expect a response indicating which dates provided in the payload are available and optionally the total price to charge the client.

Can can be used alongside the various Managing dates and prices outside of TourCMS APIs and the post-booking webhook to keep TourCMS in sync with a third party reservation system. Alternatively TourCMS can carry out the integration work for you by adding your reservation system to our Sync tool - contact us for more information.

Trigger

A call is made to the Check Tour Availability API that would return dates TourCMS thinks are available.

Currently only fired for "Departures", not "Freesale Seasons" or "Hotel" type dates - those currently continue to be booked without calling the webhook).

URL

Configure your URL in Configuration & Setup > Webhooks and TourCMS will immediately begin checking it for availability data, to remove the check just remove the URL.

Payload

TourCMS sends a JSON payload containing basic tour information plus an array of the departures it believes are available.

The payload may be extended in the future with additional data fields without warning.

Payload example

{
    "account_id": 4069,
    "account_name": "Testoperator",
    "channel_id": 3930,
    "tour_id": 1,
    "tour_code": "",
    "supplier_tour_code": "",
    "supplier_id": "0",
    "agent_id": "0",
    "agent_credentials": "",
    "sale_currency": "EUR",
    "dates": [
        {
            "date_id": "1234",
            "date_type": "departure",
            "start_date": "2018-06-01",
            "end_date": "2018-06-01",
            "code": "",
            "guide_language": ["en", "fr"],
            "note": "",
            "start_time": "",
            "end_time": "",
            "spaces_remaining": "20",
            "supplier_note": "abc",
            "rates": [
                {
                    "rate_id": "r1",
                    "name": "",
                    "agecat": "a",
                    "quantity": 3,
                    "rate_code": ""
                }
            ]


        }
    ]
}

 

Payload details

Payload details
KeyNotes
account_id TourCMS Account ID
channel_id TourCMS Channel ID
tour_id TourCMS ID for the Tour to be checked, this is the unique identifier for this particular tour on this account
tour_code TourCMS tour code, freetext entered by tour operator staff and may not be unique
supplier_tour_code Freetext entered by tour operator staff within TourCMS, designed to store an identifier for the tour in a third party system. E.g. if you are using this webhook to integrate with a third party reservation system, this would be a good place to store the third party reservation system ID for this tour.
supplier_id ID for the internal supplier record if one is configured within TourCMS, otherwise "0".
agent_idTourCMS internal ID for agent
agent_credentialsFurther information
sale_currencyThe currency TourCMS is selling in. If you are responding with prices they must be expressed in this currency otherwise your response will be considered invalid.
dates[ ]

An array of objects, one for each date TourCMS thinks are available, containing:

KeyNotes
date_id TourCMS ID for this date.
 
If date_type is "departure" then this will be the Departure ID, as used in the various raw departure APIs in Managing dates and prices outside of TourCMS.
date_type TourCMS supports various date types for availability checking however currently this webhook is only fired for "departure" type dates.
start_date The start date TourCMS has for this date.
 
ISO 8601, YYYY-MM-DD
end_date The end date TourCMS has for this date.
 
ISO 8601, YYYY-MM-DD
code The freetext code for this date
guide_language [] Tour guide language. If blank, assume all
note The freetext note for this date
start_time The start time TourCMS has for this date.
 
24 hour format, HH:MM
start_time The start time TourCMS has for this date.
 
24 hour format, HH:MM
spaces_remaining The number of spaces TourCMS thinks are available
supplier_note Supplier note (can be used for holding date specific IDs from 3rd party reservation systems)
rates [ ]

An array of objects, one for each rate that is being requested (e.g. "2 adults, 1 child" would be two rates), containing:

KeyNotes
rate_id The TourCMS ID for the rate, e.g. "r1"
name The freetext name entered for this rate in TourCMS e.g. "Adults"
agecat The age category configured for this rate in TourCMS:
 
a - Adult
s - Senior
y - Youth
c - Child
i - Infant
 
Historically TourCMS had only freetext rate names, this field has been added to aid mapping with external systems
 
For tours with no set age categories, "a" is used as the generic. E.g. "2 people" would use the age category "a".
quantity The quantity of this rate requested, e.g. a search for 3 adults would be "3"
rate_code Additional field for cross sytem mapping at a rate level. To turn on, go to configuration & setup > tour general settings

Expected response

TourCMS will wait 20 seconds for a response in the format detailed below, if the correct response is not returned within that time TourCMS will return a no availability message.

However, you should aim to reply within 2 seconds (as the customer will not wait much longer than that, on a website), or 250 milliseconds if you are selling via TourCMS to Expedia (To comply with TourCMS/Expedia SLA)

Response formats

If you are just responding to say which of the requested date(s) are available

Return a JSON array containing the date ID(s) that are available.


[2109, 111]

 

If you are also including the price TourCMS should charge:

Return an array of JSON objects, one for each of the date ID(s) that are available.

The currency in the response must match the sale_currency from the payload.

Requires a single "total price" for the date, per rate_id (i.e. total for Adults, total for Children)


[{
   "2169":{
      "r1":{
         "price":10,
         "currency":"GBP"
      },
      "r2":{
         "price":20,
         "currency":"GBP"
      }
   },
   "2170":{
      "r1":{
         "price":30,
         "currency":"GBP"
      },
      "r2":{
         "price":40,
         "currency":"GBP"
      }
   }
}]

 

More information