TourCMS, a leading online booking and channel management solution is operated by Palisis.

Contact Info

Palisis AG
Florastrasse 18A
8610 Uster
+41 44 533 40 40

Follow Us

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

Start new booking

Create a temporary booking, holding off stock for the customer


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

ExampleURL: /c/booking/new/start.xml
POST data:
<?xml version="1.0"?>
			<note>Some text</note>
			<note>Extra info</note>

Code samples

PHP examples use the PHP Client Library with SimpleXML


object start_new_booking ( SimpleXmlElement $booking_data, int $channel )


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


// 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)


XmlDocument containing the booking data
The channel we are booking with

VB examples use the .Net Client Library

Overload list

XmlDocument StartNewBooking (XmlDocument bookingData, Integer channelId)


XmlDocument containing the booking data
The channel we are booking with

NodeJS examples use the NodeJS Wrapper


  channelId: 3930,
  booking: {
    booking_key: "BOOKING_KEY_HERE",
    total_customers: 1,
    components: {
      component: [
          component_key: "COMPONENT_KEY_HERE",
  callback: function(response) {

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

Try it

Enter your TourCMS API credentials below to call the Start new booking endpoint.

Provide a component_key obtained via Check Tour Availability to book that component.

Operators (Marketplace Agent ID 0) will need to provide a value for booking_key (more info), agents must remove that node from the XML.

Take care, submitting this form will modify live data!


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

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.
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 / gift 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
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
For use by Operators only (ignored if passed by Agents). If your account is configured with TourCMS inline booking notification webhooks you can override the standard settings and for a single booking TourCMS will fall back to the standard asynchronous booking notification webhooks. Useful if you are making a temporary booking for pricing purposes only to immediately delete.

The components node containing:

XML NodeNotes

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.

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

XML NodeNotes

A reply node for each question to be answered containing:

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

An answers node containing:

XML NodeNotes

An answer node for each answer to the question:

XML NodeNotes
The answer

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

XML NodeNotes

An option node for each option to be added containing:

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

If you are booking a product with Named Tickets then you can associate specific customer records with this component. Generally not required.

XML NodeNotes

A customer node for each customer to be added containing:

XML NodeNotes
indexIndex of the customer in the order they were sent starting from 0.
rateRate of the component we want to associate with the customer.

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

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

XML NodeNotes
customer_idID number for an existing customer
titleCustomer title e.g. Mr, Mrs etc
firstnameFirst name
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)
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)

Of the customer at time of return / end of booking. Ignored if <dob> is provided.

XML NodeNotes
age_unit Either days, months, weeks or years. Generally speaking use years, however for younger travellers where more granularity is used, weeks or months may be more appropriate.
age_value Customer age at end of booking / return travel specified by age_unit, will be a whole integer
agecatAge category - 1 digit code (i-Infant, c-Child, a-Adult, s-Senior).
Alternatively if you know the customers age at time of booking or their date of birth then pass either of those instead and TourCMS will calculate the agecat automatically.
In the absence of any of these TourCMS will try to best guess age categories of booking members based on the tour(s) booked.
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)
agent_customer_refA travel agent reference number / ID for this customer, e.g. perhaps the ID for this customer in their own system

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.
If the <error> is "SUPPLIER_SUBSYSTEM_ERROR", indicating an issue starting the booking in a supplier subsystem then TourCMS will provide more information on the error that was experienced.
If the <error> is "SUPPLIER_SUBSYSTEM_ERROR", indicating an issue starting the booking in a supplier subsystem and if the subsystem has provided a textual explanation it will be included here.

This node will be returned if the tour has retricted fields and there are errors:

XML NodeNotes

A tour node for each tour of the errors node. There would be one for each tour we send by component keys (if there are errors). It contains:

XML NodeNotes
tour_idTour ID of the component/s that have errors.

This node will contain fields that are rejected based on the set restrictions:

XML NodeNotes

A field node for each field rejected. It will be rejected if the tour is configured that way and it is not sent or sent empty. It contains:

XML NodeNotes
restrictionRestriction Scope. It can be "allpax", "leadpax" or "otherpax".
nameFields due to the booking has been rejected.

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
hold_time_secondsNumber of seconds TourCMS will hold the temporary booking for, if the a commit is attempted after this point it may have expired. Default is 2700 seconds (45 minutes).
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

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. "PERCENT" for percentage based promo codes, "FIXED_VALUE" for a fixed value gift code.
value_currency Only returned for "FIXED_VALUE" gift codes, currently matches sale currency.
Membership number (if provided)

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).

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

There will be a customers node containing...

XML NodeNotes

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

XML NodeNotes
customer_idInternal ID
firstnameCustomer's first name
surnameCustomer's surname

There will be a components node containing...

XML NodeNotes

... a component node for each component, containing:

XML NodeNotes
component_idComponent ID
product_idTour 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