home > support > API > Marketplace API > booking creation > start new booking

Start new booking

Create a temporary booking, holding off stock for the customer


Notes

The temporary booking created by this method can subsequently be turned into a live booking via the Commit new booking API method.

Need to delete a temporary booking to release stock availability? Use Delete booking.

REST info

Endpoint/c/booking/new/start
FormatsXML
ExampleURL: /c/booking/new/start.xml
 
POST data:
<?xml version="1.0"?>
<booking>
	<total_customers>2</total_customers>
	<booking_key>XXX-XXXXXXX-XXXX</booking_key>
	<components>
		<component>
			<component_key>YYY-YYYYYYY-YYYYY</component_key>
			<note>Some text</note>
		</component>
		<component>
			<component_key>ZZZ-ZZZZZZZ-ZZZZZ</component_key>
			<note>Extra info</note>
			<pickup_key>TTT-TTTTTTTTT-TTTTTT</pickup_key>
		</component>
	</components>
	<customers>
		<customer>
			<title>Mr</title>
			<firstname>Joe</firstname>
			<surname>Bloggs</surname>
			<email>joe.bloggs@example.com</email>
			<tel_home>01234567890</tel_home>
		</customer>
		<customer>
			<title>Mrs</title>
			<firstname>Jane</firstname>
			<surname>Bloggs</surname>
		</customer>
	</customers>
</booking>
VerbPOST

Code samples

PHP examples use the PHP Client Library with SimpleXML

Description

object start_new_booking ( SimpleXmlElement $booking_data, int $channel )


Parameters

$booking_data
SimpleXmlElement containing the booking data
$channel
ID number for the channel the booking is being made with

Example

// Set the channel this booking will be made with
$channel = 3930;

// Start building the booking XML
$booking = new SimpleXMLElement('<booking />');

// Append the total customers, we'll add their details on below
$booking->addChild('total_customers', '1');

// If we're calling the API as a Tour Operator we need to add a Booking Key
// otherwise skip this
// See "Getting a new booking key" for info
$booking->addChild('booking_key', 'BOOKING_KEY_HERE');

// Append a container for the components to be booked
$components = $booking->addChild('components');

// Add a component node for each item to add to the booking
$component = $components->addChild('component');

// "Component key" obtained via call to "Check availability"
$component->addChild('component_key', 'COMPONENT_KEY_HERE');

// Append a container for the customer recrds
$customers = $booking->addChild('customers');

// Optionally append the customer details
// Either add their details (as here)
// OR an existing customer_id
// OR leave blank and TourCMS will create a blank customer
$customer = $customers->addChild('customer');
$customer->addChild('title', 'Mr');
$customer->addChild('firstname', 'Joe');
$customer->addChild('surname', 'Bloggs');
$customer->addChild('email', 'Email');

// Query the TourCMS API, creating the booking
$result = $tourcms->start_new_booking($booking, $channel);

$bkg = $result->booking;

// Display the temporary booking ID
print "Temporary booking ID: " . $bkg->booking_id . "<br />;

// Check whether any components were unavailable
// Non-zero would indicate some items sold out since "Check availability"
print $bkg->unavailable_component_count . " unavailable components";
Temporary booking ID: 123456
0 unavailable components

C# examples use the .Net Client Library

Overload list

XmlDocument StartNewBooking (XmlDocument bookingData, int channelId)


Parameters

bookingData
XmlDocument containing the booking data
channelId
The channel we are booking with

VB examples use the .Net Client Library

Overload list

XmlDocument StartNewBooking (XmlDocument bookingData, Integer channelId)


Parameters

bookingData
XmlDocument containing the booking data
channelId
The channel we are booking with

NodeJS examples use the NodeJS Wrapper


Example

TourCMS.startNewBooking({
  channelId: 3930,
  booking: {
    booking_key: "BOOKING_KEY_HERE",
    total_customers: 1,
    components: {
      component: [
        {
          component_key: "COMPONENT_KEY_HERE",
        }
      ]
    }
  },
  callback: function(response) {
    console.log(response.booking.booking_id);
  }
});
12345

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

Querystring parameters

There are no querystring parameters.

Post fields

The following fields can be posted as XML when calling the API, if the API is being used by a Tour Operator then a valid booking_key must be provided (see Getting a new booking key).

Post fields
XML NodeNotes
booking

The root XML element

XML NodeNotes
total_customersThe total number of customers on the booking (TourCMS will create blank customer records for any missing customer nodes up to the value of total_customers)

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 .
booking_keyMandatory if the API is being called by a Tour Operator account, not required if the API is being called by a Marketplace Partner account.
 
See Getting a new booking key.
customer_
special_request
Customers special requests / requirements. Multi-line text.
agent_refOptional travel agent reference. If there is a reference number for the booking in an agents booking system use that here - particularly if using voucher redemption

If you do not have a travel agent booking reference at this point, you can provide it at the booking commit stage.
 
Text, maximum 50 characters
tracking_miscidInteger, could be used for tracking different campaigns run via the same Partner. For use by Marketplace Partners only (the value for this will be captured automatically when a Tour Operator is using the API)
promo_codeAny promo code provided by the booker.
 
TourCMS will validate the promotional code, add any applicable discount and display the outcome in the response. Promo codes can be validated before this via a call to Show Promo.
 
Invalid promo codes, or promo codes that require a membership number but have none provided, will be ignored
promo_
membership
Used to provide TourCMS with the customers membership number (if required) that relates to the supplied promo code. In the case of a discount for a club/group this could be the customers membership number for that club.
 
Information on whether a membership number is required for a given promo code and the format it should take can be found via a call to Show Promo.
 
If a membership number is required for the promo code but not provided, the promo code will be ignored and the booking will be created without the promo code addition
components

The components node containing:

XML NodeNotes
component

There should be a component node for each item that is to be added to the booking.

XML NodeNotes
component_keyThere should be a component_key for each component, obtained via calls to the Check Tour availability API method.
noteFreetext note for this component. Visible to staff on the booking edit screen and in various reports. Can be multi-line.
 
If the item being booking is an airport transfer (product type 2) you may well be taking details like hotel names, airlines, flight numbers etc and recording them in a human-readable format. The suggested format for this is:
Airline : ExampleJet
Flight  : ABC123
Arrives : 08:15
Hotel   : Hotel Testville
pickup_keyIf the customer has chosen/entered a pickup point provide the key (as obtained from Check Tour Availability) here.
 
If the key is from one of the set list of pickup points then no further pickup information needs to be provided.
 
Alternatively, if the key is the pickup_on_request_key then you MUST also provide a pickup_note node containing the free-text pickup information entered by the customer otherwise TourCMS will silently ignore the pickup_key.
pickup_noteThe free-text pickup information entered by the customer.
 
Required if you have passed in a pickup_key node containing the value of the pickup_on_request_key field (from Check Tour Availability, indicating that free-text pickup information is accepted by the operator) otherwise leave this out/blank.
replies

If any Questions are to be answered, add a replies node containing:

XML NodeNotes
reply

A reply node for each question to be answered containing:

XML NodeNotes
question_
key
Question key identifying the question to be answered, obtained from Check Tour Availability.
answers

An answers node containing:

XML NodeNotes
answer

An answer node for each answer to the question:

XML NodeNotes
answer_
value
The answer
options

If any Options are to be booked, add an options node containing:

XML NodeNotes
option

An option node for each option to be added containing:

XML NodeNotes
component_key Component key for the option, obtained from Check Tour Availability.
customers

Customer details can be provided, or left blank and TourCMS will create blank customer records.

Alternatively provide a customer_id and TourCMS can add the booking onto existing customer records.

Alternatively, you can initially supply blank records and then update customer records subsequently (ideal if your booking flow requires you to have availability locked to you before you ask for customer details from the actual customer). To take this approach you need to use the customer_id that is sent back in the response to booking start
 
Where customers details are provided, the first customer will become the "Lead customer" on the booking and thus the primary contact.

XML NodeNotes
customer

There should be a customer node for each customer you wish to enter details for, including:

XML NodeNotes
Either
customer_idID number for an existing customer
Or
titleCustomer title e.g. Mr, Mrs etc
firstnameFirst name
surnameSurname
perm_emailWhether the customer should be opted in to email marketing or not.
 
1 = Yes
0 = No
Blank / not set = Take account default settings
 
NB: This field can only be set by Tour Operators (not Suppliers)
emailEmail address
tel_homeTel home / evening (other phone number fields are listed in the "Not so commonly used fields" section below, however if only taking one phone number then use this field)
addressAddress (can be multi-line)
cityCity
countyCounty / State
postcodePostcode / Zipcode
country2 digit country code (uppercase). Here's a HTML snippet containing all countries in a select box
middlenameMiddle name (or initial)
nationality2 digit country code (uppercase). Here's a HTML snippet containing all countries in a select box
genderThe customers gender.
 
Leave blank if gender is unknown, otherwise supply one of the following digits:
m = Male
f = Female
x = Indeterminate
dobDate of Birth (YYYY-MM-DD)
agecatAge category - 1 digit code (i-Infant, c-Child, a-Adult, s-Senior).
Alternatively if you know the customers DOB then pass that instead and TourCMS will calculate the agecat automatically.
pass_numPassport number
pass_issuePassport place of issue
pass_issue_datePassport issue date (YYYY-MM-DD)
pass_expiry_datePassport expiry date (YYYY-MM-DD)
wherehearWhere did the customer hear about us (doesn't have to be pre-configured)
faxFax number
tel_workTel work / day
tel_mobileTel mobile
tel_smsTel sms
contact_noteContact note (e.g. don't call before 8pm)
dietDietary requirements
medicalMedical conditions
nok_nameEmergency contact name
nok_relationshipEmergency contact relationship
nok_telEmergency contact telephone number
nok_contactEmergency contact other note (can be multi-line)

Response fields

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

If the temporary booking was created there will be a booking node containing the following:

XML NodeNotes
booking_idID number for the new temporary booking
channel_idChannel ID
account_idAccount ID
booking_engine_urlA URL that the customer could be redirected to to complete their booking using the standard hosted booking engine.
 
The simplest way to use this is to allow you to build a shopping cart. Just replace the first step of the booking engine with your own custom code to check availability for tours and add them to a basket before handing off to Step 2 of the booking engine using this link.
 
Or, if you also supply customer contact details, the link to the standard hosted booking engine will jump all the way to the payment stage.
 
The “Very basic booking engine” sample code shows an example of this hand-off when booking a single product.
 
It is possible to disable the standard booking engine, so on some accounts this may be blank.
balance_owed_byWho owes the primary balance on the booking.
A for Agent, C for Customer
sale_currency3 letter currency code, e.g. USD, GBP, NOK
sales_revenueNumeric sales revenue for the booking (Retail price)
sales_revenue_displayDisplay version of sales revenue, including currency symbol
sales_revenue_due_nowNumeric amount due now.
 
If you are taking payment when making the booking, this is the minimum amount you should take. The maximum you should take is indicated in the sales_price_due_ever.
 
This is not necessarily a sum of the parts you have added. Could be equal to the sales_revenue, or could be less / zero (agent paying the balance so nothing to pay now, or only deposit required now), could also be more than the sales_revenue (if a credit card fee has been applied)
sales_revenue_due_now_displayDisplay version of sale_revenue_due_now, including currency symbol/code if applicable
sales_price_due_everNumeric amount due for the booking to be considered fully paid
 
If you are taking payment when making the booking, this is the maximum amount you should take. The minimum required is indicated in the sales_revenue_due_now.

For travel agent bookings, whereby the travel agent is paying the balance, this will be the sales_revenue less their commission - so will be the value to be invoiced to the travel agent
sales_price_due_ever_displayDisplay version of the sales price due ever, including currency symbol/code if applicable
promo

If a promo code has been provided when starting the booking, a promo node will be returned containing:

XML NodeNotes
promo_code Confirmation of the promo code that was provided, e.g. "10PERCENT"
valid Whether the promotional code was valid or not. Will be "OK" if valid, if the promo isn't recognised, or doesn't apply to any of the items in the booking it will be "INVALID PROMO CODE", if the promo code requires a membership but none was provided it will be "MEMBERSHIP REQUIRED"
value The value of the promotional code (e.g. "100")
value_type What the value is expressed as. Currently only "PERCENT" however in the future may be "FIXED_VALUE" to indicate a fixed amount in the sale currency.
customer_promo
_membership
Membership number (if provided)
booking_fee

If a booking fee has been configured on the channel (supplier), a booking_fee node will be returned containing the details.
 
TourCMS will have added the booking fee on automatically if there is one.

XML NodeNotes
description Text description, e.g. "Booking fee"
fee Numeric fee value
fee_display Display version of the fee, including currency symbol
fee_type PER_PERSON = Fee will be charged per person
PER_BOOKING = Fee will be charged per booking
available_component_countNumber. This should hopefully be equal to the number of component nodes submitted.
unavailable_component_countNumber. This should hopefully be 0 (zero)
 
Used to indicate whether any items could not be added to the booking (perhaps they sold out between the initial availability check and now).
unavailable

If any components are unavailable TourCMS will attempt to indicate which elements are no longer available

XML NodeNotes
component_key Component key for the unavailable item
lead_customer_idID number for the lead customer
customers

There will be a customers node containing...

XML NodeNotes
customer

... a customer node for each customer, contaiing:

XML NodeNotes
customer_idInternal ID
If booking as a Marketplace Agent
commissionTotal amount of commission on the booking
commission_displayDisplay version of the commission, including the currency symbol/code where appropriate
commission_currencyThree letter code for the currency the commission is returned in (e.g. USD, GBP, EUR etc)
commission_taxTotal amount of commission tax on the booking
commission_tax_displayDisplay version of the commission tax, including the currency symbol/code where appropriate
If booking directly as the Tour Operator (not as a Marketplace Agent)
creditcard_fee_typeInteger representing if and how the preconfigured credit card fee applies. If adding a payment using the Create Payment method you will be passing the credit card fee type there.

More information