home > support > API > Marketplace API > Voucher redemption > search vouchers

Search Vouchers

Get a list of bookings and any of their components that are due to start today that match a voucher barcode


Notes

Search TourCMS using the data from a TourCMS or supported OTA voucher barcode and retrieve a list of components available to be checked in.
 
Either scan the voucher barcode, or if you know the details of a TourCMS booking that you want to search for you can obtain the barcode data via Show Booking, or construct your own barcode data in the format: TOURCMS|account_id|booking_id.

REST info

Call/c/voucher/search
FormatsXML
ExampleURL: /c/voucher/search.xml
 
POST data:
<?xml version="1.0"?>
<voucher>
	<barcode_data>12345</barcode_data>
</voucher>
VerbPOST

Code samples

PHP examples use the PHP Client Library with SimpleXML

Description

object search_voucher ( SimpleXmlElement $voucher_data [, int $channel = 0 ] )


Parameters

$voucher_data
XML containing the voucher info to search, currently just the barcode data
$channel
If authenticating as an operator use their Channel ID, Agents skip this / pass 0

Example

// Tour Operators set their channel here
// Marketplace Agents don't need to specify one
// Used for API authentication only, not searching bookings
$channel = 0;

// Create a new SimpleXMLElement to hold the voucher details
$voucher_data = new SimpleXMLElement('<voucher />');

// Include the contents of the barcode
$voucher_data->addChild('barcode_data', '12345');

// Query the TourCMS API
$results = $tourcms->search_voucher($voucher_data, $channel);

// Loop through each booking
foreach($results->booking as $booking) {

  // If the booking is valid
  if($booking->booking_valid == "OK") {

	  // Print out the booking ID
	  print $booking->booking_id

	  // Loop through all the components on the booking
	  foreach($booking->component as $component) {
	  	// Output the tour name and redemption status
	  	print " " . $component->name;
	  	print " (" .  $component->voucher_redemption_status . ")";

	  }
  } else {

      // There is some problem with the booking
      print $booking->booking_id . " " . $booking->booking_valid_reason;

  }
}
123455 - Half day rafting (1)
123456 - Half day rafting (0) Off-road (1)
123457 - BOOKING NOT CONFIRMED
123458 - Half day rafting (1)

C# examples use the .Net Client Library

VB examples use the .Net Client Library

NodeJS examples use the NodeJS Wrapper


Example

// Search for vouchers containing the text VOUCHER_STRING_HERE
// the wideDates param being set to 1 causes TourCMS to include dates other than today in the search
TourCMS.searchVouchers({
  channelId: 3930,
  voucherString: "VOUCHER_STRING_HERE",
  wideDates: 1,
	callback: function(response) {
		console.log("Found " + response.booking.length + " bookings")
	}
});
Found 2 bookings

Looking for sample code in a different language? TourCMS and community provided API libraries

Querystring parameters

N/A

Post fields

Post the contents of the barcode found on the voucher. Or, if you have the details of a TourCMS booking construct the barcode data manually.

Post fields
XML NodeNotes
voucher

XML NodeNotes
barcode_data The information from the voucher barcode. This can be a TourCMS barcode or a supported OTA / Travel Agent barcode
 
OR
 
If you know the details of a TourCMS booking that you want to search for you can obtain the barcode data via Show Booking or construct your own barcode data in the format: TOURCMS|account_id|booking_id
 
OR
 
Just send the TourCMS booking ID
 
OR
 
Also searches the lead customer surname, includes partial matches from the start (e.g. 'kha' matches 'Khan' but not 'Beckham')
 
OR
 
Blank to return all bookings
surname Search for vouchers based on the lead passengers surname specifically, includes partial matches
surname_start Like <surname> but only matches from the start (e.g. 'kha' matches 'Khan' but not 'Beckham')
wide_dates Generally the voucher search is useful for for tours starting today only. If you want to search for last 60 days to future 60 days, send wide_dates as 1.

Response fields

TourCMS will return all matching bookings and - if a given booking is valid - any of its components due to start today.

Response fields
XML NodeNotes
request Confirmation of the request that you sent
error Any error message returned, if there is no error this will just contain the text OK
booking

There will be one booking node for each booking matching our barcode data.

Each booking node contains the following child nodes.

XML NodeNotes
booking_idTourCMS ID number for the booking, will be unique per channel but not unique accross all channels
account_idTourCMS ID number for the account the booking was made with
booking_validWhether the booking is valid or not
 
"OK" indicates that the booking is valid and has some components that can be redeemed / checked in
 
"INVALID BOOKING" indicates that the booking is not available for redemption / checking in and the clients voucher may need to be rejected. The reason for this will be given in "booking_valid_reason".
booking_valid_reasonIf "booking_valid" includes anything other than "OK", this field will give a human readable explanation of why the booking is invalid and the clients voucher may need to be rejected. This could be due to the booking being cancelled, unconfirmed (unpaid) etc.
channel_idChannel ID
channel_nameChannel name, usually the tour operator (supplier) brand name this booking was made under
logo_urlLogoo for the tour operator (supplier channel the booking was made under, usually the tour operator logo
lead_customer_idLead customer id
lead_customer_nameThe lead customer's full name. E.g. "Mr Joe Bloggs"
lead_customer_firstnameThe lead customer's first name. E.g. "Joe"
lead_customer_surnameThe lead customer's last name. E.g. "Bloggs"
sale_currencyThe currency the booking was made in. E.g. "USD"
balanceThe remaining balance on the booking, numeric. E.g. "0.00" if no balance remaining.
balance_displayDisplay version of the balance remaining, includes currency information. E.g. "£0.00"
balance_owed_byWho owes the primary balance on the booking
'A' for Agent, 'C' for Customer
has_local_paymentWhether the boking has "Local payment" items (i.e. payable in destination rather than pre-payable). Depending on the account settings, local payments may not be included in the overall booking total
agent_refFree text agent reference number. Generally we suggest agents enter a reference for the booking from their own booking system if one exists.
promo_code_questionA free text field regarding any promo code the client used when booking that requires further attention. Perhaps "Verify client has their AAA membership card".
customer_special_requestAny special request made by the customer at the time of booking, free text. Could be "Please ensure I have a window seat due to travel sickness"
component

If the booking is valid (see "booking_valid") there will be one component node for each component on the booking, due to start today

Each component node contains the following child nodes.

XML NodeNotes
component_id Component ID
name The name of the component (tour). E.g. "Half day rafting" or "Transfer to Hotel"
code The tour code. Could be the departure time, could be a free text identifier used by the operator
rate_description E.g. "Adult", "Child", "Luxury"
sale_quantity_description Number of people / quantity of the "rate_description" booked. E.g. "2"
start_date Start date for the component. Should be todays date (in the timezone of the tours account). YYYY-MM-DD
end_date End date for the component. YYYY-MM-DD
note
voucher_redemption_status Whether this particular component has already been redeemed. "0" = Not redeemed yet, "1" = Already redeemed
redeem_voucher_key If the "voucher_redemption_status" for this component is "0", this field will be present and contain a key that can be passed to Redeem Voucher to redeem the voucher
redeem_voucher_key_reverse If the "voucher_redemption_status" for this component is "1" (i.e. the component has previously been redeemed) this field will be present and contain a key that can be passed to Redeem Voucher to reverse the redemption and set the voucher_redemption_status back to "0".
bus_checkin_status If the tour operator (supplier) has bus checkins switched on this field will be returned and will indicate whether this particular component has already been checked in. "0" = Not checked in by the bus driver yet, "1" = Already checked in by the bus driver
bus_checkin_key If the "bus_checkin_status" for this component is "0", this field will be present and contain a key that can be passed to Redeem Voucher to check the client in on the bus
bus_checkin_key_reverse If the "bus_checkin_status" for this component is "1" (i.e. the client has already been checked in by the bus driver) this field will be present and contain a key that can be passed to Redeem Voucher to reverse the checkin and set the bus_checkin_status back to "0".
questions

If any questions were configured when this component was booked then a questions node will be returned containing:

XML NodeNotes
q

There will be an q node for each question, containing:

XML NodeNotes
question_keyIf answering using Update Booking Component this key will be used to identify which question is being answered.
questionThe primary question text to display to the customer, e.g. Please provide the approximate weights for each member of your party in kilograms (Kg)
explanationAdditional explanation text for the question, perhaps detailing why it is being requested or how it will be used
placeholderPlaceholder text, usually an example of the type of input required
question_internalA shortened label for the text, largely intended for staff use, e.g. Weight (kg)
repeatInteger. How many answers are expected. Some questions should be answered once per tour booking, others should be answered once per person, this field will display the correct number of answers expected, e.g. "2"
repeat_typeString. The value of the setting that drives the quantity, currently either 'Q' (if the question is set to be answered per person/quantity) or '1' (if the question is set to be answered once per tour booking)
answer_typeAn indication of the type of input expected, e.g. 'text', 'number', 'date' (and possibly more in future). Note that as far as the API goes this a suggestion only, TourCMS does not validate that the correct type of data is provided in an answer.
answer_mandatoryWhether the answer is mandatory (required). Note that as far as the API goes this is a suggestion only, TourCMS allows mandatory questions to be omitted or left unanswered
answers

An answers node containing:

XML NodeNotes
answer

An answer node for each answer to the question:

XML NodeNotes
answer_
value
The answer

More information