Access Keys:
Skip to content (Access Key - 0)

Interface Definition for Tourplan hostConnect

hostConnect Versions: 4.01.000 and above
Date: 2018-10-18

Table of Contents

1 Overview

hostConnect is designed to provide access to Tourplan for server-side scripts and host to host integration. This document details the basic interface between hostConnect and the scripts or systems that use it. The XML DTD includes some elements that are only available on a restricted basis; these elements are not covered in this document.

This section gives an overview of the interface. The overview comprises details of changes in this version, an introduction to the request and reply formats, hostConnect, a summary of how data items are named in each of the formats, details of the various data types used for values specified in request and reply messages, a discussion of some data items that appear in several messages, and an overview of some of the terminology used in this document.

The second section specifies the request types supported by the interface, including details of data items within each request and each reply.

1.1 Changes in this version

Significant changes between this version and version 4.00:

  1. New request  GetProductSearchData.
  2. GetBooking  returns additional information about each extra.
  3. A number of requests can now return full booking details (that is, the same data as available from  GetBooking). They are  AddService,  CancelServices, and  DeleteService.
  4. GetBooking  now returns  CanCancel, which specifies whether the booking can be cancelled via  CancelServices. Also, the rules for whether a booking can be cancelled have been tightened. It is no longer possible to cancel a booking whereby only some services would end up with a cancelled status. Now, all services in a booking must either not need cancelling (because they are already cancelled, for example), or must be able to be cancelled.
  5. Cancel policies can now be defined in Tourplan. This means extra information is returned by  OptionInfo  and  GetBooking. Also,  DeleteService  and  CancelServices  can now create cancel penalty service lines.
  6. In  OptionInfo  stay pricing,  RoomType  is now optional when searching for rates. The room types used to calculate a stay price are now returned.
  7. An  Age  can now be supplied instead of a  DateOfBirth.

1.2 Formats for hostConnect requests and responses

Host systems and server-side scripts communicate with hostConnect using HTTP GET or POST requests, made to the URL that hostConnect is installed under. hostConnect requests and responses are XML documents. A DTD specifies the formats of XML documents exchanged by hostConnect. Each XML document sent to hostConnect has a   Request   root element, and each XML document sent by hostConnect has a   Reply   root element.

The usual way of sending an XML requests is to send a HTTP POST with a content type of   text/xml, and the XML document in the body of the POST request. The content type of the reply message is also   text/xml. Alternatively, the XML document can be supplied as the value of the XML parameter in form-urlencoded format in a GET or POST request. In this case the reply message is   text/xml.

Each XML document sent to the hostConnect has a   Request   root element, which contains a single element whose name is the name of a hostConnect request concatenated with the string   Request. An analogous situation exists for XML documents sent by hostConnect in reply.

The URI in the DOCTYPE declaration in the request should simply be the name of the DTD (hostConnect_4_00_000.dtd for example) and  not  an absolute URI (such as http://www.tourplan.com/support/Connector/hostConnect_4_00_000.dtd).

In version 3.00.272 and above, if the Accept-Charset HTTP header is present, it determines the character set encoding of the reply. In earlier versions, or if the header is not present, or has a value of *, then a default encoding will be used (most likely ISO-8859-1 or UTF-8).

If the   CompressReply   attribute of the   Request   element is set to   Y, then the   Content-Encoding   header in the HTTP is set to   gzip   and the data in the reply is compressed using gzip (the OptionInfo   request can produce large reply messages). If   CompressReply  is set to N   then the reply is not compressed. If   CompressReply   is not specified then if Accept-Encoding in the HTTP request header contains gzip, then the reply is returned compressed with gzip. Otherwise, the reply is not compressed.

In the documentation below, data item names are names of elements. Names are case sensitive.

1.3 Data types

In section 2, a data type is specified for each data item. The basic data types used are: String, Integer, Boolean, Date, Time. The following points clarify how values of these data types are represented.

  • A maximum length is associated with some string input data items (if a maximum length applies it is shown in parentheses in the type column of the data item table). An error message is returned if a value supplied for such a field is longer than the specified maximum.

  • Some input string fields (currently   Remarks   in  AddService  and   Remarks   in  SetBookingRemarks ) are permitted to contain multiple lines. In this case, a newline (line feed) character is used as the line terminator. Note that because carriage return/line feed sequences may be used internally in Tourplan, each line feed character in a remarks field should be regarded as two characters in terms of the maximum field length limit.

  • For some integer fields, minimum and/or maximum values are shown in the type column in parentheses.

  • A boolean value is encoded as a single character:   Y   for true;   N   for false.

  • A date value is encoded in   yyyy-mm-dd   format.

  • A time value is encoded in   hhmm   format, with values ranging from 0000 to 2359.

  • A timestamp value has second-resolution, and is returned in the format described in the W3C note on time and date formats.

  • Prices are stored as integers. Prices returned are Tourplan prices multiplied by 100 (see the  OptionInfo  section for details of exchange rate conversions).

  • In an integer list, a single space is used to separate integer values.

1.4 Common data items

Some data items appear in several requests and/or replies. To avoid duplication, details of a number of them are given here. Also, the   Request   element has a number of optional attributes, which can be supplied for any request.

Attributes of the   Request   element:

Data itemTypeDescription
CompressReplyBooleanIs the XML reply compressed using gzip? Optional, defaults to false.
ReturnWarningsBooleanShould warning messages be returned? At present only OptionInfo returns warnings. Optional, defaults to false.

Fields common to a number of requests:

Data itemTypeDescription
AgentIDStringAgent internet usercode
PasswordStringAgent internet password
BookingIdIntegerUnique identifier for a Tourplan booking
RefString (10)Tourplan booking reference. Bookings can be identified in all requests by their reference or their id. It is better to use the booking reference to identify bookings. In the request specifications that follow, the term booking identifier will be used to mean that either BookingId/Id or Ref can be supplied.
ReturnBooking
NoteFormat
ReturnPackageServices
ReturnAccountInfo
 A number of booking update requests can return details of the booking as it stands at the completion of the booking update. This happens if  ReturnBooking  is true. If a booking is returned then the other fields affect what booking information is returned. See  GetBooking  for descriptions of these fields.

1.5 Cancellation policies

Prior to version 4.01.000, the CancelPolicies element was used for returning details of cancellation policies that applied to external rates. From version 4.01.000 on, cancellation policies can be defined in Tourplan. These policies are returned (within a  CancelPolicies  element) by OptionInfo (for each of the rate formats supported) and by GetBooking. For an internal rate, every  CancelPenalty  element contains a deadline in hours (the number of hours is returned in the  OffsetUnitMultiplier  field). This is followed by either rules about how cancellation penalty amounts are calculated, or the values that would be charged (which of these is returned depends on context). These fields are documented in the table below. A penalty applies if cancellation occurs within the specified number of hours of service date. If multiple penalties meet this criterion, then the penalty with the smallest number of hours applies. For example, if there were penalties for 24, 72 and 240 hours, and the cancellation occurred 48 hours in advance of service date, then the 72 hour penalty would apply (we are still outside the 24 hour period, and 72 is the smaller of 72 and 240).

Data itemTypeDescription
CancelRuleTypeStringThe method used to calculate cancellation penalty amounts. One of Average (the average per SCU amount multiplied by some value), Percent (percentage of the amount), Fixed (a fixed amount) and First or Last (the cost of the first or last SCU units).
CancelRuleUnitsDecimal (2dp)Value used in conjunction with  CancelRuleType  to determine the penalty amounts. For Average the average amount is multiplied by this value. For Percent this value is the percentage to apply. For First and Last this value is the number of SCU units to charge for (the value must be an integer). For Fixed this field is not returned.
LinePriceIntegerAmount of the cancellation penalty.
AgentPriceIntegerLinePrice  less commission.
SellPriceIntegerLinePrice  converted to  SellCurrency.

1.6 Agent logins and sub-logins

Each agent has a "main" iCom login (and password), which are supplied to most hostConnect requests as  AgentID  and  Password. It is also possible to setup agent "sub-logins" in addition to the main login. Things to note about sub-logins:

  • Wherever login details are required, in the form of values for   AgentID   and   Password, a main login or a sub-login can be supplied.

  • The behaviour of some requests is not affected by whether a main login or a sub-login is used. These tend to be the requests that retrieve database information, and include AgentInfo, OptionInfo, GetLocations, GetServices and SupplierInfo.

  • For requests that act on bookings, if the main login of an agent is used then any of that agent's bookings can be acted on, whereas if a sub-login is used only bookings associated with that sub-login can be acted on. Requests in this category include AddService, DeleteService, CancelServices, QuoteToBook, GetBooking, PriceBooking, SetBookingRemarks, GetBookingMessage, Resequence, AddDialogueEntry and ListBookings.

  • If a sub-login is used for an AddService request, any value supplied for Consult is ignored.

  • Most of the functionality provided by the requests for managing sub-logins (GetAgentSublogins, AddAgentSublogin, UpdateAgentSublogin, DeleteAgentSublogin) is only available to main logins. See the detailed documentation of these requests for details.

1.7 Terminology

Many hostConnect requests manipulate bookings in some way. Tourplan distinguishes between two types of booking: confirmed bookings and quotes. A quote is basically a form of price enquiry. Consequently, inventory is not reserved for the various services within a quote. A confirmed booking is an actual booking. Consequently, inventory is reserved for each service with a confirmed booking. Note that it is possible to convert a quote to a confirmed booking, at which time an attempt is made to take inventory for each service in the booking.

In this document, the term booking will be used to refer collectively to quotes and confirmed bookings. In other words, booking should be read as quote or confirmed booking.

Each booking contains 0 or more service lines (sometimes referred to as services). Each service line includes one option (sometimes called a service option) in a booking.

2 Request types

This section provides interface details for all of the request types (the name of each request is specified in its sub-section heading).

In response to a request, hostConnect produces either a reply (of a type that matches the request, as detailed below) or an error reply. In an XML error reply, an   ErrorReply   element appears within the   Reply   element.

The following data items appear in an error reply:

Data itemTypeDescription
ErrorStringA string that contains three sub-fields (including an error number). See the Standard iCom Error Messages page for more details.
ErrorDataStringThis optional string is used in some requests to supply further error information. Any use of ErrorData by a request is detailed in the request's sub-section below.

2.1  Ping

The   Ping   request is provided as a simple way of determining whether hostConnect is alive.

Input data items

None.

Output data items

Data itemTypeDescription
VersionStringThe version number of hostConnect.
BackendStringSpecifies whether the underlying Tourplan system is iS or V5 (iS is the only value that will be returned).

2.2 AgentInfo

The   AgentInfo   request returns information about the specified agent (and as with other requests that require   AgentID   and   Password   an error is reported if the   AgentID   /   Password   combination is invalid).

Input data items

AgentID  Password. Also:

Data itemTypeDescription
ReturnAccountInfoBooleanIf Y then accounting information is returned in the AgentCurrencies and Balances elements. Optional (defaults to N.
ReturnLastReceiptBooleanOnly relevant if accounting information is returned. If Y then LastReceiptAmount and LastReceiptDate are returned for each agent currency (otherwise these values are not returned). Optional (defaults to N.

Output data items

The first group of data items is always returned. The remaining ones, for agent currencies and balances, are only returned if accounting info has been requested. The data items always returned are:

Data itemTypeDescription
CurrencyStringThe currency this agent operates in.
EmailStringThe agent's email address.
NameStringThe agent's name.
PriceCodesStringPrice codes.
IsSubLoginBooleanIs this agent login a sub-login?
HasBookingRightsBooleanDoes a sub-login have the same rights as the main agent login?

If accounting information is returned then details of each currency an agent transacts in are returned in an   AgentCurrencyInfo   element. The data items for this element are:

Data itemTypeDescription
CurrencyStringThe currency code.
CreditLimitIntegerThe credit limit for this currency. If 0 then no credit limit has been set.
LastReceiptAmount
LastReceiptDate
Integer
Date
The amount and date of the last receipt transaction. Only present if ReturnLastReceipt is Y and there is at least one receipt.

If accounting information is returned then details of the balances of each currency an agent transacts in are returned in an   Balance   element. The data items for this element are:

Data itemTypeDescription
CurrencyStringThe currency code.
CurrentBalanceIntegerBalance for the current period. The total balance is this amount plus the four overdue amounts.
Overdue1 to Overdue4IntegersBalances overdue for the previous accounting period (Overdue1), the period before that (Overdue2) and so on. Overdue4 includes all other earlier periods.
Future1 to Future4IntegersBalances that will become due in the next accounting period (Future1), the period after that Future2 and so on. Future4 includes all other later periods.
FutureEnteredIntegerBalance of all transactions that will occur in a future period.

2.3  OptionInfo

The   OptionInfo   request returns information about one or more options. The request specifies a combination of details to be returned, from the list: general information, stay pricing and availability, rate information, availability information, detailed availability information, enquiry notes, detailed enquiry notes, amenities, FYIs, replicated locations encountered in the search, replicated locations for suppliers, pickup points for suppliers.

Each option has two unique identifiers: its option identifier and its option number. The OptionInfo and AddService requests accept either for the purposes of identifying a particular option, and the OptionInfo request returns both. Of the two, the option number is less likely to change over time. The supplier code component of the option identifier will very likely change if the supplier name changes, and supplier name changes are not uncommon. Other components of the option identifier (such as location and service codes) are much less likely to change over time, but such changes occur occasionally.

Options are specified to the   OptionInfo   request as zero or more option identifiers and zero or more option numbers, and zero or more (button name, destination name) pairs (at least one of these must be specified).

Input data items

AgentID  Password. Also:

Data itemTypeDescription
OptString (17)

Tourplan option identifier (Location + Service + Supplier + Option code). Location must be exactly three characters, service two characters and supplier six characters. Trailing spaces can be omitted from the option code.

Zero or more option identifiers are to be specified.

pattern is an option identifier that contains one or more   ?   characters. When a pattern is specified it is checked against all option identifiers, and details about those that match the pattern are returned.

OptionNumberIntegerTourplan option number. Zero or more option numbers are to be specified.
ButtonName
DestinationName
String
String
Zero or more pairs of these fields can be specified. For each pair, the options associated with the service button, destination name pair are included in the search.
InfoStringSpecifies the categories of option data to return. One letter is used to specify each category of data are available, and any combination of the available letters can be specified: G (general), A (availability), I (detailed availability), R (rates), S (stay pricing and availability), D (rate date ranges), B (package details), N (enquiry notes), T (multiple enquiry notes), F (FYIs), M (amenities), L (supplier replicated locations, LocationCodes only), P (supplier replicated locations, LocationCodes with pickup points), V (replicated locations encountered in search). If the Info data item is empty, or is omitted, then only option identifiers and ValidLocations are returned. Note that only one of the rate types (RSD) can be asked for. Also, if S is asked for then no A or I data is returned.
DateFromDateStart date for rate and availability information. If DateFrom is not specified then start date defaults to today (on the computer hostConnect is running on).
DateTo
SCUqty
Date
Integer (1..)
DateTo and SCUqty are alternatives for specifying the duration of the period that stay, rate and inventory information is required for. If SCUqty is specified it is the length of the period (days/nights). If DateTo is specified then SCUqty is DateTo minus DateFrom plus 1. If neither is specified then SCUqty defaults to 1.
ACacheBooleanIf the data item value is true (or if the ACache data item is omitted) then availability information returned (if any) is retrieved from the cache within hostConnect. If the value is false then availability information is retrieved from Tourplan (this provides somewhat more up to date information, but is considerably slower). Because of the performance penalty, this data item should be set to N in situations where it is important to get up to date availability information for a small groups of options (for example, as part of the checking process in finalising a booking).
RateConvertBoolean

If the data item value is true then all rate information is converted to the currency associated with the specified agent. If it is false, no rate conversions are performed, and rates are returned in the currency in which they are stored. If RateConvert is not specified then whether currency conversion occurs or not is determined by a system default.

Note: this data item has no effect if   R   or   S   is not specified in   Info.

RoomConfigXML elementThe room configuration being priced. See the the  AddService  section for more information on RoomConfig. Note that PersonId cannot be specified in an OptionInfo RoomConfig as it is only valid for booking operations, such as AddService (people are attached to bookings). This data item has no effect if S is not specified in Info.  RoomType  is optional. If it is not specified then (for a room-based option) a room type will be assigned based on the pax numbers in the room. The room types assigned are returned as part of the stay pricing data.
MinimumAvailabilityStringOnly options with this availability or better have their details returned. Permitted values are OK (option is available for the specified stay), RQ (option is OK or can be requested), NO (return all options). Optional (defaults to RQ). Note: this data item only has an effect if S is included in Info, or if R is included in Info and room configurations are supplied.
SortField
Ascending
String
Boolean
If any sorting of the options is required, a SortOrder element appears, which contains one or more SortField elements. Each of these elements in turn contains a FieldName and an Ascending (optional) element (defaults to true), which specifies whether the sort is in ascending or descending order on that field. If there is more than one SortField element, then each successive element specifies a subsort. 
Valid values for FieldName are: suppliername, optiondescription, optioncomment, localitydescription, classname, rate, availability, optioncode (Location+Service+Supplier+Code), suppliercode, supplieranalysis1-6, dbanalysisCode1-6 and option (code only). The rate and availability fields are those determined by stay pricing, and if stay pricing is not requested then these two fields do not affect the sort order (that is, all options returned are deemed to have the same rate as each other, and the same availability).
IndexFirstOption
MaximumOptions
Integer (0..)
Integer (0..)
These two fields can be used together (or individually) to limit the number of options returned. These values are applied to the list of options that would have been returned had these values not been specified. If IndexFirstOption is specified then it is the 0-based index into this list of the first option returned. If MaximumOptions is specified then no more than this number of options is returned. Generally these fields will be used in conjunction with some specified sort order.
NoteCategoryStringWhere multiple note categories are available and only one is required, NoteCategory is used to specify the category of the note to return.
LocationCodeString (3)Specifies that only SupplierLocations matching this code should be returned (if a LocationCode is supplied then Info is treated as containing P, but restricted to the location specified).
LocalityDescriptionStringIf specified, only options in this locality are returned. Optional.
ClassDescriptionStringIf specified, only options with this class are returned. Optional.
DescriptionStringIf specified, only options whose description contains the specified description are returned. Optional.
SupplierNameStringIf specified, only options whose supplier name contains the specified supplier name are returned. Optional.
LastUpdateFromTimestampIf specified, only options whose LastUpdate time is greater than or equal to the supplied value are returned. Optional.
LastUpdateToTimestampIf specified, only options whose LastUpdate time is less than or equal to the supplied value are returned. Optional.
RatePerScuBooleanOnly relevant for stay pricing. If true, then the stay price returned is a per scu (e.g. per day or per night) rate. If false (the default) then the rate for the entire stay is returned. Optional.
NoteFormatStringFormat to return notes in. One of T (plain text returned) or H (HTML returned). Optional (defaults to plain text).
NotesInRtfStringDeprecated (has been replaced by  NoteFormat). Format to return notes in. One of N (plain text returned), Y (plain text returned; it was formerly used to ask for RTF, but that format is no longer supported) or H (HTML returned). Optional (defaults to plain text).
PriceCodeStringPrice code(s) of rates to return (a single price code, or a comma-separated list of price codes). Optional. This field is not available at some hostConnect sites (depends on configuration settings in hostConnect).
Branch
Department
SalesAnalysis1 to
SalesAnalysis6
StringsThese fields are all optional. By default costing is done in the context of a booking made with the default values for all of these fields. For each one supplied, the value supplied is used instead of the default in the costing process.
PaxBreakChildRatesBooleanOnly relevant for Info R and D. If true then child and infant rates will be returned for each defined pax break. If false or not supplied (the default) then child and infant rates are only one value. This functionality is only relevant to non-accommodation and package services that have pax breaks defined. Optional.

Examples of option patterns:

  • QTSSSAJHAC BUNGEE identifies a single option.
  • SYDAC???????????? matches all Sydney accommodation options.
  • SYD??SYDLUX?????? matches all Sydney options offered by supplier SYDLUX.
  • ????????????????? matches all options.

Output data items

The   OptionInfo   request returns information on 1 or more options. Information on each option is returned in an   Option   element.

For each option whose details are returned, the Option identifier and number are always returned. Also, if the search finds an option under multiple location codes (because the option's supplier has replicated locations, and because the option is found under two or more replicated locations based on the search criteria), then the locations the option is found under are returned within a   ValidLocations   element (the   LocationCode   values returned within   ValidLocations   are a subset of the supplier's replicated locations).

Data itemTypeDescription
OptStringThe option identifier.
OptionNumberIntegerTourplan option number.
LocationCodeStringA replicated location code the option has been found under in this particular OptionInfo request.

Additional groups of values may be returned, as specified in the   Info   input data item. If amenities are requested, then all option and supplier amenities are returned. If FYIs are requested, then all FYIs that apply for the specified period are returned (if no period is specified then all FYIs are returned). See the SupplierInfo section for details of how amenity and FYI data is returned. Other groups are discussed below.

General group

This group of data items appears within an   OptGeneral   element. Note that the way in which information on (the up to 5) extras is presented differs significantly between the two formats. If there are any extras an   OptExtras   element exists, that contains one or more   OptExtra elements. Each   OptExtra   element contains the number of the extra the information relates to, as well as the two pieces of information about the extra. If extra N is not defined then no information is returned for that extra.

Data itemTypeDescription
SupplierIdIntegerSupplier number. Note that the supplier number and the supplier code in the option identifier both identify the (same!) supplier that the option is associated with.
SupplierNameStringSupplier name.
DescriptionStringOption description.
CommentStringOption comment. Each hostConnect implementation is configured either to always return this field or never to return it.
VoucherNameStringName printed on vouchers for this option.
Address1
Address2
Address3
Address4
Address5
PostCode
StringThe address printed on vouchers.
LocalityStringOption locality code (returned if non-blank). The uses of locality codes are site-specific.
LocalityDescriptionStringDescription associated with the option's locality code (returned if non-blank).
ClassStringOption class code (returned if non-blank). The uses of class codes are site-specific.
ClassDescriptionStringDescription associated with the option's class code (returned if non-blank).
PeriodsIntegerDuration of the service option in 24 hour periods (returned only if greater than 1). For most options this field is not relevant. Examples of options where Periods is greater than one are multi-day packages, and multi-day sightseeing trips (river cruises for example).
MoreInformationURLStringURL that can be accessed to get access to more information about this option (returned if non-blank).
STypeStringOne character that specifies the service type of the option. One of: Y (accommodation), A (apartment), P (package), N (non-accommodation). If the service type is Y or P then the option is room-based (pricing is room based, when a service line is added to a booking for this option then a room type must be supplied). The difference between Y and P is that packages are fixed length (hence a number of nights is not specified).
MPFCUInteger

Charging multiple. This field is reported for non-accommodation and apartment options. For apartments it gives the maximum number of adults that one apartment can hold.

For non-accommodation options, if MPFCU has a value of 1 then rates for the option are per-person. If MPFCU is greater than one then rates for this option are for a group, and MPFCU is the maximum number of people (adults plus children) that can be booked per   AddService   call for the option. A rental car might have an MPFCU of 4, for example.

SCUStringSecond charge unit. If the option has a second charge unit (accommodation options generally have "Nights" as a second charge unit, for example) then this data item is present and contains the name of the second charge unit (if the option has no SCU then this data item is omitted from the reply). Note that if an option has the same values for MinSCU and MaxSCU then hostConnect will not return the SCU, MinSCU and MaxSCU fields.
MinSCUStringMinimum number of second charge units (appears only if the option has a second charge unit).
MaxSCUStringMaximum number of second charge units (appears only if the option has a second charge unit). Currently MaxSCU will be no more than 99.
Single_AvailSingle_Ad_Max
Single_MaxTwin_Avail
Twin_Ad_MaxTwin_Max
Double_AvailDouble_Ad_Max
Double_MaxTriple_Avail
Triple_Ad_MaxTriple_Max
Quad_AvailQuad_Ad_Max
Quad_Max
Boolean, Integer, Integer triplesThese fields are returned for room-based options (which is determined by SType). For each room type, the _Avail flag is always present, and specifies whether the room type is available for this option. If the room type is available, then the _Ad_Max field is present and specifies the maximum number of adults that the room can accommodate. If a particular limit has been set for the maximum number of adults plus children that a room type can accommodate, then this is returned as _Max.
InfantsAllowed
ChildrenAllowed
AdultsAllowed
BooleanThese fields specify whether this option accepts bookings for each of the three age categories (infants, children and adults).
Infant_FromInfant_To
Child_FromChild_To
Adult_FromAdult_To
IntegerThese fields return the age ranges for infants, children and adults. A (from, to) pair is not returned if either of the following two: that age category is not allowed (as per the boolean flags described below), or age details have not been entered into Tourplan. ranges do not overlap.
CountInfantsInPaxBreak
CountChildrenInPaxBreak
BooleanThese fields are returned for apartments and options with pax break pricing. They specify whether infants and children should be counted when determining the pax total that decides the apartment rate, and which pax break should be used.
ButtonNameStringThe service button this option is associated with.
DBAnalysisCode1 to
DBAnalysisCode6;  DBAnalysisDescription1 to
DBAnalysisDescription6
StringThe database analysis codes and descriptions. Tourplan has 6 database analysis codes. Configuration settings determine which (if any) are returned by hostConnect.
LastUpdateTimestampOptionInfo returns a mixture of option and supplier level information. LastUpdate is the date of the last change to the option and supplier level information in the database (changes to availability do not affect the LastUpdate time).
SequenceNumberIntegerAn extra number (in the range 1 to 5).
DescriptionStringThe description of an extra charge.
ChargeBasisString

An extra can be charged per group, per room, or per person. Some extras are compulsory, which means the extra is automatically booked (and the quantity is calculated). Non-compulsory extras are only booked if an extra quantity that is greater than 0 is supplied when a booking is made. The quantity specifies how many of the extra is needed. For example, a breakfast is usually a Pax or Nights extra. When booked the quantity is usually the number of nights in the stay. The charge basis is one of:

  • Group. The rate is per group (there is one group per service line).
  • Room, RoomNights. The rate is per room booked in the service line.
  • Pax, Nights. The rate is per person booked in the service line.
  • Rate. A compulsory extra that is charged per person for each day there is a non-zero rate.
  • FirstRate. compulsory extra that is charged per person on the first day on which there is a non-zero rate.
  • GroupRate. A compulsory extra that is charged per group for each day there is a non-zero rate
  • GroupFirstRate. A compulsory extra that is charged per group on the first day on which there is a non-zero rate.
IsPricePerPersonBooleanIf true, then the extra is charged per person (in other words, it has a charge basis of Pax, Nights, Rate or FirstRate).
SupplierLocation Code and List of PickupPoints

Further discussion will help to clarify the meaning of some of the data items in this group.

For some options, a booking for that option will involve specifying the number of time units the booking is for. For example, an accommodation option will be booked for some number of nights, and a rental car for some number of days. The units of day and night are the most common time units though others, such as hour, are used in some Tourplan systems.

The generic Tourplan term for these various time units is Second Charge Units, or SCU for short. If an option has an SCU, then the number required can be specified using the SCUqty field of an AddService request made to add that option to a booking. Internally within Tourplan, most (perhaps all) options have an SCU defined. Many of these are not time based, however, such as CLIMB, CRUISE, MEAL, TICKET and TOUR. In calls to AddService, only requests that relate to options that have time-based SCUs should specify an SCUqty. The time-based SCUs will vary a little between Tourplan systems, but DAY and NIGHT will usually cover nearly all cases.

We can identify three types of options on the basis of some of the fields described above:

Room-based

A room-based option has an SType of Y or P. The difference between an SType of Y and an SType of P is that for type Y options (accommodation) an SCU applies to specify the length of the stay, whereas if the SType is P (package) no SCU applies as the package is for a fixed number of days.

Group-based

A group-based option has an SType of A, or an SType of N and MPFCU of more than 1.

Pax-based

A pax-based option has an SType of N and MPFCU of 1.

The option type makes a difference in a number of situations, including:

  • It determines the form in which rate information is returned (see below).
  • MPFCU is only returned if SType is N or A.
  • When AddService is called for a room-based option the type of room being booked must be specified.
  • When a room-based or group-based option is booked using AddService, one unit of inventory is consumed (1 per room booked for room-based). When a pax-based option is booked using AddService the number of units of inventory consumed is the number of adults plus the number of children.
  • Limits on the number of adults and children that can be booked in a single call to AddService depend on the option type (see the  AddService  section for details).
Enquiry notes group

There can be multiple notes fields per option. If   N   is specified in   Info   then   OptEnquiryNotes   is included in the reply. Its value is all available notes are concatenated together. If   T   is specified in   Info   then the available notes are returned individually, with the note category and note text returned for each. If a value is supplied for the   NoteCategory   input field (and   T   is not included in   Info  ) then only notes of the specified category are returned.

Data itemTypeDescription
OptEnquiryNotesStringOption enquiry notes.
NoteCategoryStringThe note category code (the type of note this is).
NoteTextStringThe contents of the note.
LastUpdateTimestampWhen the note was last changed.
The stay pricing group

If  S  is specified in the  Info  data item, then stay pricing and availability are returned for each option. The parameters of the stay are supplied in the input parameters  DateFrom,  RoomConfig, and  SCUqty  or  DateTo. An option that does not have a valid rate for a booking made today, for the specified start date, room configuration and length of stay is omitted from the reply. Also, only options with the specified MinimumAvailability are returned.

Rates are returned in the currency associated with the agent identified by the  AgentID  data item unless the  RateConvert  data item has a value of  N  (in which case they are returned in the currency they are stored in). The conversion rate for  DateFrom  is the one used to do the conversion.

Data itemTypeDescription
AvailabilityStringThe availability of this option for the specified stay. One of NORQOK. The remaining fields only appear if Availability is not NO.
CurrencyStringThe currency that TotalPrice is in.
TotalPriceIntegerThe total price of the stay (totalled across all rooms and all second charge units) for this option.
CommissionPercentDecimal (2dp)Percentage of commission applicable to TotalPrice
AgentPriceIntegerTotalPrice less commission.
RateIdStringAn internal Tourplan identifier for this rate. Must be supplied to AddService if this rate is booked.
RateNameString (20)The name of the rate that applies on the first day of the stay.
RateTextString (60)Rate description for the rate that applies on the first day of the stay. Omitted if blank.
MinSCUIntegerIf there is a minimum number of days or nights required to qualify for the rate returned then MinSCU specifies this minimum. Omitted if no minimum.
Stay
Pay
IntegerIf a stay/pay deal has been applied in the price calculation then this pair of fields appears and gives details of the stay/pay deal applied.
CancelHoursIntegerCancellations within this number of hours of service date incur a cancellation penalty of some sort.
LastBookableDateDateSome rates have to be purchased a minimum period in advance. If there is such a requirement for these rates, this field is present and is the last date on which these rates are available for booking. Otherwise, this field is not present.
SaleFromDateRates in this date range cannot be sold before this date. Optional (does not appear if the sale from date in Tourplan is before January 1st, 2000).
SaleToDateRates in this date range cannot be sold after this date. Optional (does not appear if the sale to date in Tourplan is more than 5 years in the future).
PriceCodeString (2)Price code of rate. Optional. This field is not available at some hostConnect sites (depends on configuration settings in hostConnect).
RoomTypeStringFor room-based options, a  RoomList  element is returned containing one or more  RoomType  values (one per  RoomConfig  specified in the request). For each  RoomConfig  in the request, if a  RoomType  was supplied then the corresponding  RoomType  in the  RoomList  will have the same value. Otherwise, the  RoomType  value will be the one assigned and costed. The reason for returning the room types is so they can be used in any subsequent  AddService  request.
PeriodValueAddsXML elementIf present,  PeriodValueAdds  contains additional information about the rate returned, and contains one or  PeriodValueAdd  elements. Each  PeriodValueAdd  has a start date, an end date, the rate name for the period, the rate text for the period (if not blank) and a collection of zero or more value adds for the period
PeriodValueAddXML elementContains  DateFrom,  DateTo,  RateName,  RateText  (optional) and a collection of zero or more value adds that apply during the period. Each value add has a  Type  and a  Description
TypeStringThe type of value add. The types are IncludedExtra and Descriptive. For IncludedExtra the value in  Description  is the name of a compulsory extra that has been charged for in the stay price. The other types are various pieces of descriptive text about the rate. The Type element can have a  Number  attribute that contains an integer. For type IncludedExtra the number is the extra number. For type Descriptive the number is the rate voucher text field number.
NumberIntegerThe  Type  element can have a  Number  attribute. For type IncludedExtra the number is the extra number. For type Descriptive the number is the rate voucher text field number.
DescriptionStringThe descriptive text for a value add.
CancelPenaltyXML elementEach  CancelRule  element contains  CancelHours,  LinePrice, and  AgentPrice.

If a rate has been retrieved from an external system, then   OptStayResults   contains a   ExternalRateDetails   element with additional information about the external rate. The fields present within   ExternalRateDetails   are listed below.

Data itemTypeDescription
ExtSupplierIdStringThe identifier for the supplier used in the external system.
ExtOptionIdStringThe identifier for the option used in the external system.
ExtOptionDescrStringOption description used in the external system.
ExtRatePlanCodeStringThe external system's rate plan code for the rate returned.
ExtRatePlanDescrStringDescription of the rate plan code.
ExtGuaranteeStringThe type of guarantee that must be supplied to the external system in order to book this rate. One of N (none), C (credit card), P (pre-pay using credit card) or A (agency). For an agency guarantee the details passed through are configured into Tourplan. Where a credit card is involved, credit card details can be supplied to AddService.
DetailNameDetailDescriptionStringsMiscellaneous data returned by an external system that does not fit into any other field is returned as DetailNameDetailDescription pairs, in an AdditionalDetail element.
CancelPoliciesXML elementAny cancel policies returned by the external system are reported under this element, in one or more CancelPenalty elements. Each of these elements contains an optional PenaltyDescription, and an optional deadline. The deadline is absolute (in which case the time component is always returned, and the date component can be returned) or relative (which is returned as units and multiplier).
OffsetTimeUnitStringOne of Second, Hour, Day, Week, Month or Year.
OffsetUnitMultiplierIntegerThe number of OffsetTimeUnit in this relative deadline.
DeadlineDateDateDate component of absolute deadline.
DeadlineTimeTimeTime component of absolute deadline.
DepotDetailXML elementOptional data that is relevant for rental car services which will describe the depot information that the rate pertains to.

Services that are connected to external rental car systems will return additional information describing the depot configuration that the rate pertains to.  The Point_ID values must be used when adding a service of this type.

PickupDetailXML elementData describing the pickup information relevant to the rate.
DropoffDetailXML elementData describing the drop off information relevant to the rate.
LocationCodeStringThe location code that the car is being picked up/drop off from
Point_IDIntegerThe internal identifier of the Tourplan pickup/dropoff point
ExternalDepotIDIntegerThe external suppliers depot identifier for the pickup/dropoff point
PointDescriptionStringThe description/name of the pickup/dropoff point
GroupNumberIntegerInternal grouping number for the pickup/dropoff point
The rate group

If  R  is specified in the  Info  data item, then rate information is returned for each option. The main difference between the information returned in the rate group and the stay pricing is that the rate group presents information on all rates associated with an option (all room types, all apartment sizes, all extras, and so on), whereas stay pricing is focused on a particular number of pax staying in a particular room configuration.

The rates returned are on the basis of a stay starting on  DateFrom, of the length given by  SCUqty  or  DateTo. An option that does not have a valid rate for a booking made today, for the specified start date and length of stay is omitted from the reply. In other words, an option that cannot be booked today for the specified start date and length of stay is not returned.

Rates are returned in the currency associated with the agent identified by the  AgentID  data item unless the  RateConvert  data item has a value of  N  (in which case they are returned in the currency they are stored in). The conversion rate for the  DateFrom  is the one used to do the conversion.

Rates are returned within an  OptRates  element. Rates for each day are returned in an  OptRate  element. Note that for options for which the SCU quantity does not apply (such as transfers) rates are returned for one day (  DateFrom  ).

If a  RoomConfigs  element is provided in the input then then  Availability  is returned for each day, and for the period as a whole (in this case it is the weakest availability across all of the daily availabilities). Also, if  RoomConfigs  and  MinimumAvailability  elements are provided then only those options whose overall availability is at least the specified minimum availability are returned. See the stay group section for a description of the Availability item.

Data itemTypeDescription
CurrencyStringThe currency of the rates returned.
PaxBreaksInteger listSome type N (non-accommodation) and type P (package) options have rates that depend on the number of people travelling. If an option has pax-break pricing, then PaxRates reports the pax break ranges (PaxBreak elements nested within a PaxBreaks element). The integers given show the start of each pax range. So, if we have the list 1, 3, 4, 8, the ranges are 1-2, 3, 4-7, 8-MPFCU. The number of adults plus (if CountChildrenInPaxBreak is true) the number of children plus (CountInfantsInPaxBreak is true) the number of infants is what determines which pax break range is applied.
MinSCUIntegerIf this value appears, then the rates returned are on the basis of a minimum night stay (or days hire) of MinSCU. If MinSCU is not reported then there is no minimum that applies during the period (effectively the minimum is 1). This feature is often used to enforce minimum night stay rules of hotels during special events.
CancelPenaltyXML elementEach  CancelRule  element contains  CancelHours,  CancelRuleType, and  CancelRuleUnits  (not present if the rule type is Fixed).
DateDateThe date that this set of rates applies to.
RateNameString (20)The name of the rate that applies on this day of the stay.
RateTextString (60)Rate description for the rate that applies on this day of the stay. Omitted if blank.
ValueAddsXML elementContains a collection of value adds that apply on that date. Each value add has a  Type  and a  Description  (see the stay pricing section for more information).
FreeOfChargeBooleanIf this field is present, and is Y, then this particular day of the stay is free of charge due to a stay / pay deal. The rates returned for this day show what the day would have cost had it not been free. Note that one or more extras can be chargeable on a free day. Each such extra will contain a  FreeOfCharge  element (as a child of the  ExtrasRate  element) with a value of  N.
Availability
(within OptRates)
StringOverall availability for the whole period (the weakest availability over all days of the period covered). Possible values are described in the stay pricing section.
CancelHours
(within OptRates)
IntegerOverall cancel hours for the whole period (calculated from the cancel hours of the days in the period covered). See the stay pricing section for more details in this field.
LastBookableDate
(within OptRates)
DateSome rates have to be purchased a minimum period in advance. If there is such a requirement for these rates, this field is present and is the last date on which these rates are available for booking. Otherwise, this field is not present.
SaleFrom
(within OptRates)
DateRates in this date range cannot be sold before this date. Optional (does not appear if the sale from date in Tourplan is before January 1st, 2000).
SaleTo
(within OptRates)
DateRates in this date range cannot be sold after this date. Optional (does not appear if the sale to date in Tourplan is more than 5 years in the future).
PriceCode
(within OptRates)
String (2)Price code of rate. Optional. This field is not available at some hostConnect sites (depends on configuration settings in hostConnect).
CommissionPercentDecimal (2dp)Percentage of commission applicable to the rates returned.
AdultRateChildRate,
InfantRateOptionRate
Integer

These data items appear in the reply if and only if the option has a service type of   A   or   N.

If the service type is   A   then there are MPFCU values and child and infant rates (the child rate is omitted if it is 0, and likewise for the infant rate). The MPFCU different values give the rates if 1 adult stays in the apartment, 2 adults, and so on up to MPFCU adults.

If the service type is   N   and the MPFCU of the option is one, then pricing is per person. One adult rate is returned (one adult rate per pax range if the option has pax breaks). Child and infant rates handling is as described above unless the service has pax breaks and  PaxBrakChildRates  is supplied and set to  Y. In that case a child and an infant rate will be returned for each pax break defined. In this case, zero rate values are returned.

If the service type is   N   and the MPFCU of the option is greater than one then pricing is per group (of up to MPFCU adults plus children). One group rate is returned (one group rate range per pax range if the option has pax breaks). The group rate(s) appear as   OptionRate   elements within a   OptionRates   element.

SingleRateDoubleRate,
TwinRateTripleRate,
QuadRateExtraAdultRate
ExtraChildRateInfantRate
AdultRate
Integer

These data items appear in the reply if and only if the option has a service type of   Y   or   P   (in other words, if and only if rates are room based). The five room rates and three extra pax rates appear as separate elements within a   RoomRates element. Any zero rates are omitted. Some packages have room and pax break pricing. For these packages, the   PaxBreaks   element contains details of where the pax break boundaries are, and the   AdultRate   elements here give the rates for those various pax breaks (  AdultRate   elements appear only for packages that have room and pax break rates).

By default,  ExtraChildRate  and  InfantRate  are single values and are omitted if zero. However, if the Package has pax breaks defined and the  PaxBreakChildRates  is set to Y then a child and an infant rate for each pax break is returned, including zero values.

The   ExtraAdultRate   is relatively rare. It only applies for options that can accommodate more than four adults (up to the maximum given by   MaxAdult  ). So, for 6 adults, for example the rate that applies is the Quad room rate plus twice   ExtraAdultRate. The   ExtraChildRate   is the per child cost of any children over and above the room capacity (if this rate is 0 then any such children are free of charge). For example, with two adults and two children in a triple room then one child is charged at   ExtraChildRate. All infants are charged at the   InfantRate.

Availability
(within OptRate)
StringAvailability for a particular day. Possible values are described in the stay pricing section.
CancelHours
(within OptRate)
IntegerCancel hours for a particular day. See the stay pricing section for more details in this field.
SellBeforeTravelIntegerSome rates have to be purchased a minimum period in advance. If there is such a requirement for these rates, this field is present and is the number of days or months in advance that the rate must be purchased. For example, if there is a 7 day sell before period, then a booking for 2012-09-27 must be made no later than 2012-09-20. This field is not present if there is no sell before requirement.
SellBeforeTypeString (1)Present if and only if  SellBeforeTravel  is present, and specifies the units of  SellBeforeTravel. D means days and M means months.

If there are rates for 1 or more extras, then an   ExtrasRates   element appears, that contains one   ExtrasRate   element for each extra for which rate information exists.

Data itemTypeDescription
SequenceNumberIntegerThe number of the extra that this rate applies to.
FreeOfChargeBooleanOnly relevant if the main rates for the day are free of charge. If this extra is charged for on a free of charge day, then this element is present and is  N.
AdultRateIntegerAppears for extras charged per person.
ChildRateIntegerAppears for extras charged per person (if non-zero).
InfantRateIntegerAppears for extras charged per person (if non-zero).
ExRateIntegerAppears for extras charged per group.
The date range group

If   D   is specified in the   Info   data item, then date range rate information is returned for each option. The two forms of rate information described above (stay pricing, rate group) are based on rates that apply for a stay that starts on a particular date and has a particular length. Date range rates show rates that apply for the various rate seasons present within a specified period.

The date ranges returned are those found within a period whose start date is   DateFrom   and whose end date is determined by   SCUqty   or   DateTo   (as per the other rate requests). Options that do not have valid rates within the specified period are not omitted from the reply.

Rates are returned in the currency associated with the agent identified by the   AgentID   data item unless the   RateConvert   data item has a value of   N   (in which case they are returned in the currency they are stored in). The conversion rate for the   DateFrom   is the one used to do the conversion.

If the option has pax breaks, then these are returned as a child element of the   OptDateRange   element (the format is the same as that used for pax break information in the rate group).

If the option has cancel policies in the requested period then they are returned in a  PeriodCancelPolicies  element, which contains one or more  PeriodCancelPolicy  elements. Each  PeriodCancelPolicy  element has a  DateFrom  and  DateTo, and details of the cancel penalties that apply in that period. Each  CancelPenalty  element contains a deadline in hours,  CancelRuleType, and  CancelRuleUnits  (not present if the rule type is Fixed). Each  PeriodCancelPolicy  covers a distinct period (cancel policy periods cannot overlap).

Zero or more   OptDateRange   elements are returned. The date ranges are in increasing date order, and do not overlap. There can be gaps between one date range and the next. The   DateFrom   of the first date range is never before the   DateFrom   supplied to the   OptionInfo   request (even if the date range in Tourplan starts before   DateFrom  ). Likewise the   DateTo   of the final date range never goes past the end of the period enquired on.

Each   OptDateRange   contains one or more   RateSet   elements. Usually there is a single   RateSet   element, but there are multiple if there are different rates for different lengths of stay/hire period, and/or different rates on different days of the week (weekend/weekday rates for hotels, for example). If there are multiple   RateSet   elements, then each combination of day of the week and length of stay will be covered by at most one   RateSet.

The data items in the   OptDateRange   and   RateSet   elements are listed below. The main rates are returned in the   OptRate   structure already discussed in the rate group section. Note that the non-rates elements of   OptRate   are omitted in this context (most of them can be found in the   RateSet   element). In some cases rates are expressed as a being a certain amount per night for the first N nights, and a different amount per night thereafter. Where details of one of these "special" rates are returned, the   MinSCU   element specifies the number N (the rate is only available for a stay of N or more nights), the   OptRate   element contains the rates for each of the first N nights, and the   ExtraNightRates   element contains the rates for extra nights (note that rates for all optional extras are stored against the   OptRates   rates, which is why there is no   ExtrasRates element in   ExtraNightRates.

Data itemTypeDescription
PriceCodeString (2)Price code of rate. Optional. This field is not available at some hostConnect sites (depends on configuration settings in hostConnect).
DateFromDateThe start date of the date range.
DateToDateThe end date of the date range.
SaleFromDateRates in this date range cannot be sold before this date. Optional (does not appear if the sale from date in Tourplan is before January 1st, 2000).
SaleToDateRates in this date range cannot be sold after this date. Optional (does not appear if the sale to date in Tourplan is more than 5 years in the future).
CurrencyStringThe currency of the rates returned.
SellBeforeTravelIntegerSome rates have to be purchased a minimum period in advance. If there is such a requirement for these rates, this field is present and is the number of days or months in advance that the rate must be purchased. For example, if there is a 7 day sell before period, then a booking for 2012-09-27 must be made no later than 2012-09-20. This field is not present if there is no sell before requirement.
SellBeforeTypeString (1)Present if and only if  SellBeforeTravel  is present, and specifies the units of  SellBeforeTravel. D means days and M means months.
RateNameString (20)The name of the rate.
RateTextString (60)Rate description. Omitted if blank.
ValueAddsXML elementContains a collection of value adds that apply for the rate set. Each value add has a  Type  and a  Description. Value adds of type IncludedExtra do not appear (they are not relevant for this type of rate request). See the stay pricing section for more information on the  ValueAdds  element.
MinSCU
MaxSCU
IntegersThe rate set applies where the SCU quantity (number of nights, days, whatever) falls on or between these two numbers.
AppliesDaysOfWeekBoolean attributesIf this element is omitted then the rates in this rate set apply on every day of the week. If this element is present then the rates in this rate set apply on the days whose attributes have a value of true (attribute names are Mon, Tue, Weds, Thur, Fri, Sat, Sun).
IsClosedBooleanIf true then this a closed rate set, and no rates are available. In this case none of the following XML elements are present.
ScuCheckOverlapOnlyBooleanControls what is checked where a stay includes parts of two or more rate sets, and one of the rate sets has a MinSCU greater than 0. If this value is true then the number of nights by which the stay overlaps the rate set period is validated against MinSCU. Otherwise the full length of the stay is validated against MinSCU.
CancelHoursIntegerCancel hours for booking made using this rate set. See the stay pricing section for more details in this field.
StayPayIntegersZero or more (stay, pay) pairs give the details of stay/pay deals that apply for rates in this rate set. For each stay/pay deal, if you stay for "stay" nights then you only pay for "pay" nights (in other words, "stay" - "pay" nights are free of charge). Where multiple stay/pay deals apply, they are in increasing order of stay length. Also, for any particular booking only one stay/pay deal applies; the one with the biggest "stay" value that is less than or equal to the length of the stay of the booking. Each  Stay/  Pay  pair is within a  StayPay  element, and all of these elements are under a  StayPays  element.
SequenceNumberIntegerBy default, extras are free on days that are free of charge due to a stay / pay deal. If one or more extras is charged for on such days, then the  StayPays  element contains a  ChargedExtras  element, which has one or more  SequenceNumber  child elements. These child elements contain the sequence numbers of extras that are charged for on days where the main rates are free due to a stay / pay deal.
The availability group

Note that for it to be possible to book a service line there must be a valid rate. The availability returned only shows availability based on product inventory and/or whether the product is available on a request or freesell basis. It does NOT check or guarantee that there is also a valid rate for the dates searched for.

Data itemTypeDescription
OptAvailInteger list

Each integer in the list gives the availability for one of the days in the range requested, from the start date through to the end date. The integer values are to be interpreted as follows:

  • Greater than 0 means that inventory is available, with the integer specifying the number of units available. For options with a service type of Y, the inventory is in units of rooms. For other service types, the inventory is in units of pax.
  • -1 Not available.
  • -2 Available on free sell.
  • -3 Available on request.

Note: A return value of 0 or something less than -3 is impossible.

The detailed availability group

In Tourplan, it is possible for one option to have inventory of several unit types. For example, an accommodation option may have (on a particular night) 2 single rooms and 1 double room available.

The availability group of return values is able to accurately return inventory details for an older generation Tourplan that did not support unit types, but is not powerful enough to handle some situations that can occur in Tourplan. If an option has inventory of two or more types, then the values are combined together to arrive at the information returned in the availability group. In the example before (2 single rooms and 1 double room available), a value of 3 (rooms) would be returned in the availability group.

It may be the case that a company using hostConnect to interface with a Tourplan system decides that the inventory information provided by the availability group is accurate enough (especially if the are few, if any, options that have inventories of more than one unit type). If, however, availability information is needed for each unit type, then the detailed availability group is available.

Detailed availability information is returned within a   DetailedAvails   element. Inventory information is returned as UnitType, OptAvail element pairs, with each pair within a   DetailedAvail   element.

Note that for it to be possible to book a service line there must be a valid rate. The availability returned specifies what the availability is if and only if there is a valid rate. It is possible for the returned availability on some particular day to be on request, for example, but for an attempt to book a service on that day to be rejected because there is no valid rate.

Data itemTypeDescription
UnitTypeUnit type list

The unit type(s) that apply (a single space follows each unit type). For accommodation options, the following unit types apply: sg (single), db (double), tw (twin), tr (triple), qd (quad), ot (other). At present Tourplan allows for one of these, or all of these. For apartments all room types are listed.

For non-accommodation options, the following unit types apply: ad (adult), ch (child). A list of ad by itself means that only adults consume inventory. A list of ad and ch means that adults and children consume inventory. No other combinations are currently supported.

OptAvailInteger listAs for the availability group.
Replicated locations encountered in search

If   V   is specified in the   Info   data item, then for each option returned that has replicated locations, the list of one or more replicated locations the option is found by in this search is returned. The locations the option is found under are returned within a   ValidLocations   element (the   LocationCode   values returned within   ValidLocations   are a subset of the supplier's replicated locations). If the search is restricted to a single location or destination then generally there is a single   LocationCode   returned. Note that when booking an option whose supplier has replicated locations, a   LocationCode   should be supplied to   AddService   to specify which location is required.

Data itemTypeDescription
LocationCodeStringA replicated location code the option has been found under in this particular OptionInfo request.
Replicated locations and pickup points

If   L   or   P   is specified in the   Info   data item, then for each option returned that has replicated locations then the full list of replicated locations for the supplier is returned (and if   P   is specified details of any pickup points are also returned). The   SupplierLocations   element contains one or more   SupplierLocation   elements, each of which contains a location code, and zero or more pickup points.

Note that a pickup point can be specified in an   AddService   call by supplying the   PointDescription   as   puRemark   (for a pickup) or   doRemark   (for a dropoff).

Data itemTypeDescription
CodeStringA replicated location code.
Point_IDIntegerUnique pickup point identifier.
PointDescriptionStringPoint description (Sydney airport, for example).
CanPickupBooleanAre pickups allowed at this pickup point.
CanDropoffBooleanAre dropoffs allowed at this pickup point.
Package details

If   B   is specified in the   Info   data item, then for each option returned that is a package then details of the services options that make up the package are returned. Details of each service option included in a package are returned in a   PackageServiceLine   element. The   PackageDetails element contains the   PackageServiceLine   elements.

Data itemTypeDescription
DayNumberIntegerWhich day this service option is booked relative to the date the package is booked (which is day 1).
SequenceNumberIntegerUsed to order service options with the same day number.
SCUqtyIntegerNumber of second charge units.
OptStringThe option identifier.
OptionNumberIntegerTourplan option number.
AvailabilityStringReturned if RoomConfigs has been supplied. The availability calculation is based on DateFrom as the booking date of the package, and the room configuration provided. One of NORQOK.

2.4 AddService

A booking is built up service by service. Each   AddService   request adds one service to a (new or existing) booking. Note that for a service to be added to an existing booking the agent adding the service must be the same as the agent who made the original booking.

Input data items

The input data items can be divided into three groups:

  1. Data items that are specified only for the first service added to a new booking.

  2. Data items that are specified only for a service added to an existing booking.

  3. Data items that apply to services added to new and existing bookings. This group includes   AgentID   and   Password. This group also includes  ReturnBooking  and associated fields.

The data items provided in an   AddService   request are either groups 1 and 3 (for the first service in a new booking) or groups 2 and 3 (for a service added to an existing booking). In the discussion below, each group has its own section (except group 3 which has two sections).

New booking group

The new booking group of data items appear within a   NewBookingInfo   element.

Data itemTypeDescription
NameString (60)Name of the party for whom the booking is being made (required). Note that in some systems Name is forced to upper case.
QBString (1)The QB data item can take one of two values: Q if the service is being added to a new quote; B if the service is being added to a new booking.
BranchDepartmentString (2)One or more of these optional (up to 2 character) data items can be specified for the first service added to a new booking. In each case, if the data item is specified (and the value is non-empty) it is copied into the corresponding field in the booking header. If the data item is not specified, Tourplan will determine the value to use.
SalesAnalysis1 to
SalesAnalysis6
String (2)Same comment applies as for Branch and Department
Existing booking group

The existing booking group of data items appear within an   ExistingBookingInfo   element. This group contains the booking identifier of the existing booking.

Common group (room configuration)

The room configuration (adults, children, room type(s) and pax names) are the data items that make up the room configuration data. In very early versions of hostConnect (up to 2003), room configuration consisted of three data items: Adults, Children and RoomType. This interface is still available (with the recent addition of Infants). It does have some limitations, as it is not possible to book more than one room on a service line. Also it is not possible to supply details of the pax in each room.

The preferred way to supply a room configuration makes it possible to specify multiple rooms on a service line, and to specify pax names.

There are one or more   RoomConfig   elements within a single   RoomConfigs   element. If the option being booked is not room-based, then there is a single   RoomConfig   element containing details of all pax being booked. If the option is room-based then there are one or   RoomConfig elements. Specifying pax details are optional. Where there are pax whose details are not specified (either because no pax details are specified or because the number of pax details records is less than the number of pax in the room) hostConnect will assign pax records itself (by using other pax associated with the booking that aren't included on this service and/or generating pax records).

For each set of pax details specified hostConnect checks to see whether the pax is one that is already in the booking or is a new pax. If a   PersonId   is specified then an existing set of pax details for the current booking is being used, and there must be a pax record for the current booking with the specified   BookingId. Otherwise, the supplied title, forename, surname, date of birth / age and pax type are checked against all pax in the booking. If there is an existing pax in the booking that matches on all of these fields then that existing pax is used. Otherwise a new pax for the booking is created. Note that at present hostConnect is not able to update details of a pax already in a booking.

Data itemTypeDescription
AdultsInteger (0..99)

Number of adults this booking is for. Required.

For room-based options, this parameter is used to specify the number of adults that will occupy the specified   RoomType   (see below). The number of adults cannot exceed the room's capacity. For example, no more than two adults can be booked in a double room.

For options of all types, if a pax limit has been defined for this option (via   MaxAdults   for example), a validation check is made to ensure the specified numbers of adults and children do not exceed the pax limits.

Normally a quad room can take no more than four adults. However, if the pax limits for an accommodation option allow for more than four adults then a quad room booked for such an option can have up to the pax limit. An example of this is a large suite that can take up to 6 adults. Note that if the extra adult rate is non-zero, then the fifth and subsequent adults are charged at the extra adult rate.

For group-based options, the number of adults plus children must not exceed the option's MPFCU, and the rate charged is the option rate. For apartment options the number of adults must not exceed MPFCU.

ChildrenInteger (0..99)

Number of children this booking is for. Optional (defaults to 0).

Each option can be configured to define rates for children belonging to some age range. This data item is used to specify the number of attending children who are within this age range.

For room-based options, any children over and above the room type's capacity will be charged at the extra child rate. For example, where there is an additional child rate and there are 2 adults and 2 children in a triple room then 1 child is charged at the extra child rate.

For pax-based options, each child is charged at the child rate (and each adult at the adult rate).

InfantsInteger (0..99)

Number of infants this booking is for. Optional (defaults to 0).

RoomTypeString (2)Room type being booked. This data item appears if and only if the option is room based. Legal values: SG (single), TW (twin), DB (double), TR (triple), QD (quad). The room type specified must be valid for the option being booked.
PersonIdIntegerThe id of a person already in the booking (optional). If specified, then none of the other pax-related fields (Title through to PaxType) should be specified.
TitleString (10)A person's title (optional).
ForenameString (60)A person's first name(s) (required for each set of pax details given in which PersonId is not specified).
SurnameString (60)A person's surname (required for each set of pax details given in which PersonId is not specified).
DateOfBirthDateA person's date of birth (optional).
AgeInteger (0..200)A person's age in years (optional). On input,  Age  is acted on only if  DateOfBirth  is not supplied. Note that internally Tourplan stores date of birth and not age. That means that if a pax added to a booking has an  Age  (and not a  DateOfBirth) then a date of birth is calculated from  Age  and booking travel date. For pax details returned for a service line (by  GetBooking) if the pax has a date of birth set then  Age  is returned (calculated from the service date and  DateOfBirth).
PaxTypeString (1)A person's age category: A (Adult), C (Child) or I (Infant). Required for each set of pax details given in which PersonId is not specified.
Common group (except room configuration)
Data itemTypeDescription
OptString (17)Tourplan option identifier (Location + Service + Supplier + Option code). Either Opt or OptionNumber must be supplied.
OptionNumberIntegerTourplan option number. Either Opt or OptionNumber must be supplied.
RateIdStringAn internal Tourplan identifier for this rate, as returned by OptionInfo for a stay pricing request for the option being booked, where the DateFrom and SCUqty are the same as those in the AddService request. Some existing hostConnect users might not do a stay pricing OptionInfo call before AddService. In this case a a value of Default can be supplied for RateId, which means book the normal rate for the service line.
DateFromDateStart date for the booking of this service. Required.
SCUqtyIntegerThe number of second charge units required (second charge units are discussed in the  OptionInfo  section). Should only be specified for options that have SCUs. Defaults to the minimum SCU for option Opt if not specified. Legal range is option-dependent, and is given by the MinSCU and MaxSCU values returned by OptionInfo.
OnRequestBooleanIf true then the service is to be booked "on request" even if inventory is available; if false then the standard logic is used to determine whether the service line is confirmed or placed on request. Not relevant for quotes as all service lines for quotes are added on request. Defaults to false if not supplied.
SequenceNumberIntegerIf any "extras" are required, an ExtraQuantities element appears, which contains one or more ExtraQuantityItem elements. Each of these elements in turn contains a SequenceNumber that specifies which extra is required, as well as the quantity of that extra required.
ExtraQuantityInteger (0..20)Specifies the quantity of each extra that is required. These fields are optional (0 is the default). The extra required is identified by the associated SequenceNumber. Extra N should only appear if  OptionInfo  indicated that extra N exists.
ConsultString (30)Name of the consultant making the booking. Optional. Ignored if the AgentID supplied is a sub-login. Note that in some systems Consult is forced to upper case.
AgentRefString (60)Reference used by the agent to identify the booking. Optional.
EmailString (60)An email contact address for the booking. In fact, this field can be used to store any booking-related notes that will fit into 60 characters. Optional. This value is stored in one of the 5 user text fields associated with the booking.
puTimeTimePick-up time. Optional (see note 1 below).
puRemarkString (240)Pick-up remarks. Optional (see note 1 below).
doTimeTimeDrop-off time. Optional (see note 1 below).
doRemarkString (240)Drop-off remarks. Optional (see note 1 below).
RemarksString (240 or 60000)General remarks field. Optional (see note 1 below). This value is stored in the remarks field of the service line.
LocationCodeStringFor options with replicated locations, specifies which location the service line requires (if not specified defaults to the location the option is defined for).
PriceCodeString (2)Price code to book the service line under. Optional. This field is not available at some hostConnect sites (depends on configuration settings in hostConnect).

Note 1: each service option is associated with an iCom service type. Each iCom service type has associated with it 5 boolean values that determine whether each of the various "remarks" fields (  puTime  puRemark  doTime     doRemark   and   Remarks  ) is recorded for bookings of options of that iCom service type. For each of the five fields, it is ignored if the relevant boolean value is false.

Various validation checks are made. These include that   DateFrom   is not in the past, that it is possible to confirm the booking or put the service on request (whichever is relevant), that for room-based services the room will hold the number of adults and children specified and that   SCUqty   (if specified) is in the required range.

Note that the way in which a service line is costed depends on the service type of the option.

Output data items

For the reply message, there are several valid combinations of data items.   Status   is always returned. If hostConnect itself determines the service cannot be added (even on request) on the specified date then it will simply return a   Status   of   NO, with no other values returned. Otherwise, the service line is added to the booking. In this case,   ServiceLineId  Status   and   SeqNum   are always returned, and   Id   and   Ref   are returned if this is the first service added to a new booking (in other words, if   Id   was not specified as an input data item).

Data itemTypeDescription
BookingIdIntegerThe booking id. Note that this identifier is unique amongst all bookings that currently exist. If a booking is deleted, then its booking id might be re-used subsequently.
RefStringThe booking reference. Booking references are never re-used, even after the booking is deleted.
ServiceLineIdIntegerA unique identifier for the new service line. ServiceLineId is a better service line identifier than the combination of service date and sequence number as in some circumstances the sequence number can change. If a service line is deleted, then its service line identifier might be re-used subsequently.
SequenceNumberIntegerSequence number (within date). The main use of the sequence number in Tourplan is in ordering service details in booking messages.
StatusString

The inventory status of the service line just added. Status can take one of four values:   OK   (inventory has been reserved---not possible for a service added to a quote),   RQ   (the service is on request),   NO   (this service has been declined) or   XX  (the service line is marked as cancelled).

Note that even if hostConnect has very recently indicated that inventory exists for a particular service option on a particular day, an attempt to book that inventory can put the service on request or even fail as it is possible that in the meantime all remaining inventory units have been allocated. For this reason, the   Status   value should always be checked to see whether inventory was successfully allocated or not.

SubServiceLineIdIntegerIf the service line just added has caused other service lines to be added to the booking the there is a SubServiceLineIds element returned, that contains one or more SubServiceLineId elements, each of which is the service line id of an additional service line. At present this happens in the following situations. First, where a service line is added as two or more service lines due to splitting on rate boundaries (note that very few Tourplan sites enable this). The main details returned by AddService are for the first service line. The service line ids of the other service lines are returned in SubServiceLineIds. Second, if optional package service lines are added at the same time as a package then their service line ids are returned in SubServiceLineIds (in this case the details of the package are the main return values of AddService).
ServicesXML elementDetails of the service lines just added, using the same service line structure as used in  GetBooking. The first  Service  element is for the  ServiceLineId  service line. This is followed by one  Service  element for each  SubServiceLineId. Note: not returned if  ReturnBooking  is true.
GetBookingReplyXML elementFull details of the booking. Returned if  ReturnBooking  is true.

2.5 DeleteService

Request that a service be cancelled (if it is in a confirmed booking) or deleted (if the service is in a quote). A status code is returned that shows whether the request was successful or not. If the service is deleted, it is completely removed from the booking. If the service is cancelled, then the service remains in the booking, but its status is set to indicate that a cancellation has been requested (and a cancel penalty service line is created if a cancel penalty applies).

Note that the service line to be deleted is identified either by   ServiceLineId   or by   Date   and   SequenceNumber. It is expected that   ServiceLineId   will be the preferred identification method, with   Date   /   SequenceNumber   provided for backwards compatibility.

Input data items

AgentID  Passwordbooking identifier,  ReturnBooking  and associated fields. Also:

Data itemTypeDescription
ServiceLineIdIntegerService line identifier.
DateDateDate of the service line to be deleted.
SequenceNumberIntegerSequence number of the service line to be deleted.

Output data items

Data itemTypeDescription
BookingIdIntegerThe booking id. Returned for audit purposes.
RefStringTourplan booking reference. Returned for audit purposes.
ServiceLineIdIntegerService line identifier. Returned for audit purposes.
StatusStringThe new inventory status of the service line. If the service line has been deleted the status is deleted. Otherwise, the value will be one of those listed in the description of the Status return value for the  AddService  request.
CancelPenaltyServiceLineIdIntegerReturned if a cancel penalty was created, and is the service line id of the cancel penalty service line.

2.6  CancelServices

Request that all services be cancelled in the specified booking. This request is only permitted if the  CanCancel  value for the booking is  Y. For CanCancel to be true, it most be possible to cancel all service lines that are still required (have a Status of OK or RQ). Note that if there are no required service lines then CanCancel will be false. Also note that if any required service line is booked in an external system then CanCancel will be false. To cancel a booking containing this type of service line, first cancel each service line individually.

The new status of each service line is returned.

Input data items

AgentID  Passwordbooking identifier,  ReturnBooking  and associated fields.

Output data items

The new service line statuses are returned in the same format as that used by  QuoteToBook  to return statuses. Two additional fields can be returned in each  ServiceStatus  element (details below). The fields  BookingId   and   Ref  are returned for audit purposes.

Data itemTypeDescription
CancelPenaltyServiceLineIdIntegerReturned if a cancel penalty was created for this service line by this  CancelServices  operation. It is the service line id of the cancel penalty service line.
CancelledServiceLineIdIntegerReturned if this service line is a cancel penalty created by this  CancelServices  operation. It is the service line id of the service line the cancel penalty was created for.

2.7 QuoteToBook

Convert a quote to a confirmed booking. Note that the agent requesting the quote to book operation must be the same as the agent who made the booking.

Input data items

AgentID  Passwordbooking identifier.

Output data items

The status of each of the services within the booking is returned. When a service is added to a quote, no inventory is allocated. When a quote is converted to a confirmed booking, inventory is allocated for each service line in the booking. The statuses returned by   QuoteToBook indicate whether inventory was successfully allocated or not.

A booking contains 0 or more service lines. A   ServiceStatuses   element contains details of all service statuses. It contains zero or more   ServiceStatus   elements, each of which contains details of one service status.

Data itemTypeDescription
RefStringThe complete Tourplan booking reference.
ServiceLindIdIntegerService line identifier.
DateDateStart date for the this service line.
SequenceNumberIntegerSequence number (within date) of this service line.
StatusStringThe inventory status of the service line. See the description of the Status return data item for the  AddService  request for more information.

2.8 GetBooking

This request retrieves a booking. Note that for a booking to be retrieved successfully the agent requesting the booking must be the same as the agent who made the booking.

Input data items

AgentID  Passwordbooking identifier. Also:

Data itemTypeDescription
ForceReloadBoolean

Optional (defaults to false). To improve performance, once retrieved from the database details of a booking are cached within hostConnect (until the completion of the next cache refresh, at which time hostConnect discards all cached bookings). When a   GetBooking   occurs, if details of the required booking are in the booking cache then the values returned are from the cache rather than from the database.

If a booking is changed by something other than the hostConnect (by a Tourplan user, or via webConnect for example) while the booking is held in hostConnect's cache, then these changes will not show up (via GetBooking) until the booking cache is discarded (which may be several hours later). Note that this situation is unusual; usually a booking is built up via hostConnect and, once complete, is taken over by the back office.

The   ForceReload   data item is provided for situations in which the application using hostConnect wants to force hostConnect to get the booking afresh from the database (into the booking cache) before returning information on the booking. If   ForceReload   is true then the booking is always fetched from the database. Otherwise (  ForceReload   is false or not specified) the booking is fetched only if it is not already in the cache. Note that loading the booking from the database is significantly slower then retrieving it from the cache.

ReturnRoomConfigsBoolean

Optional (defaults to false). If false returns the room configuration using the old-style room configuration of just reporting Adults, Children, Infants and RoomType. If true then the new format for room configuration is used, giving the room configuration, and the pax records for each room configuration.

ReturnAccountInfoBoolean

Optional (defaults to false). If true then accounting information is returned in an   AccountingDetails   element.

Output data items

We can separate return values into two groups: those that are related to the booking as a whole, and those that repeat zero or more times to give details of the service lines that the booking is made up of. Note that fuller descriptions of many of these data items can be found in the  AddService  section. The data items that apply to the overall booking are:

Data itemTypeDescription
BookingIdIntegerThe booking id.
RefStringTourplan booking reference.
NameStringName of the party for whom the booking was made.
QBStringOne character indicating whether this is a quote (Q) or a booking (B).
ConsultStringName of the consultant making the booking.
AgentRefStringReference used by the agent to identify the booking.
EmailStringAn email contact address for the booking.
TravelDateDateDate on which travel commences.
EnteredDateDateDate on which the booking was created.
RemarksStringThe long remarks field associated with the booking.
DialogueStringA dialogue of log entries entered externally via iCom (see  AddDialgueEntry  for how to add a new dialogue entry) and internally from within Tourplan.
BookingStatusStringThe status of the booking. Note that this is the iCom booking status (as configured in the iCom configuration settings) and not the two character Tourplan booking status.
CurrencyStringThe booking currency.
TotalPriceIntegerThe total price of the booking. Sum of all service line LinePrice values for service lines where CostedInBooking is Y
AgentPriceIntegerThe total price of the booking less commission. Optional (only returned if hostConnect is configured to return agent pricing).
ReadOnlyBooleanIf true, then this booking is read-only, and cannot be modified via iCom.
CanAddServicesBooleanIf true, then service lines can be added to this booking using AddService, and if false they cannot. It is not possible to add services to bookings that are read-only, nor is it possible to add services to some some non-internet bookings.
CanCancelBooleanIf true, then this booking can be cancelled by using a CancelServices request.
BookingTypeStringF for a fast book (FIT) booking, G for a group book booking. Currently GetBooking cannot return data for a group book booking (ListBookings can, however).
IsInternetBookingBooleanIf true, then this booking is an internet booking. If false then this is a booking created in Tourplan.

If accounting details are returned then the following fields are returned in an   AccountingDetails   element.

Data itemTypeDescription
InvoicedTotalIntegerTotal of all of the invoice (INV) transactions.
ReceivedTotalIntegerTotal of all of the receipt (REC) and cheque (CHQ) transactions.
CreditsTotalIntegerTotal of all of the credit note (CRD) transactions.
AmountDueIntegerAmount of what has been invoiced that has not yet been paid.
FutureBillingIntegerAmount that has not yet been invoiced.
TransactionsXML elementDetails of the individual account transactions. If there are one or more transactions, then a Transactions element is present and contains one or more Transaction elements. The fields listed below appear in a Transaction element.
TransactionIdIntegerDatabase id of the transaction.
DateDateDate transaction occurred on.
TransactionRefStringTransaction reference printed on documentation.
RelatedRefStringThe TransactionRef of a related transaction. For receipts and credit notes this is the transaction reference of the invoice that the receipt or credit note is related to.
TransactionTypeStringOne of INV (invoice), CHQ (cheque), REC (receipt) or CRD (credit note).
AmountIntegerTax inclusive transaction amount, in booking currency.

A booking contains zero or more service lines. A   Services   element contains zero or more   Service   elements, each of which contains complete details of one service line.

Each service line can have non-zero quantities for between 0 and 5 extras. Only extras with non-zero quantities are reported. If there are one or more non-zero extra quantities, then each is reported as a   ServiceExtra   element, all of which are within a   ServiceExtras   element.

The data items relating to room configuration are structured in the same way as they are for  AddService . Whether the old or new style room configuration format is used is controlled by the input value of   ReturnRoomConfigs.

If a service line is booked in an external system, then additional details are returned in the  ExternalServiceDetails  element.

Service lines appear in date/sequence number order.

 

Data itemTypeDescription
ServiceLineIdIntegerService line identifier.
OptStringTourplan option identifier (Location + Service + Supplier + Option code). If necessary, spaces are added to make the option identifier 17 characters long.
OptionNumberIntegerTourplan option number.
DateDateStart date for the booking of this service.
SequenceNumberIntegerSequence number (within date).
AdultsIntegerThe number of adults booked for this service.
ChildrenIntegerThe number of children booked for this service.
InfantsIntegerThe number of infants booked for this service.
RoomTypeStringThe room type booked (appears only if the option service type is accommodation or package).
PersonIdIntegerDatabase id of this person record.
TitleStringPax title (only present if one was entered).
ForenameStringPax forename.
SurnameStringPax surname.
AgeIntegerPax age (only present if one was entered).
PaxTypeStringA (adult), C (child) or I (infant).
CostedInBookingBooleanSpecifies whether LinePrice is added in to the booking's TotalPrice. Usually this field is Y, and LinePrice is included in booking TotalPrice. One reason for a service line having a value of N here is that on some systems cancelled services do not contributed to the booking total. Another is that in some systems optional extra services are added into the booking, and do not contribute to the booking total (unless the agent decides to include the optional service). If this field is N then LinePrice shows the original price of the cancelled service, or how much the option service will cost if accepted.
LinePriceIntegerThe total price of this service line. Note that it is not always the case that the service line prices sum to the booking total price. This depends on the setup of the underlying Tourplan system (sometimes taxes or rebates are applied at the booking level).
SellCurrency
SellPrice
String
Integer
A few hostConnect systems are configured to return LinePrice converted to SellCurrency (the currency that the Tourplan user is transacting with the supplier). In such systems, this pair of fields is returned, giving the sell currency, and the SellPrice (LinePrice converted to SellCurrency). Often sell currency is the same as booking currency, in which case SellPrice and LinePrice are the same).
AgentPriceIntegerThe total price of the booking less commission. Optional (only returned if hostConnect is configured to return agent pricing).
SCUStringThe second charge unit (commonly night or day). Blank if the option does not have an SCU.
SCUqtyIntegerThe number of second charge units required.
puTimeTimePick-up time (see note 1 for  AddService ).
puRemarkStringPick-up remarks (see note 1 for  AddService ).
doTimeTimeDrop-off time (see note 1 for  AddService ).
doRemarkStringDrop-off remarks (see note 1 for  AddService ).
SupplierNameStringSupplier name this service is booked for.
DescriptionStringOption description of the option this service is booked for.
CommentStringOption comment of the option this service is booked for. Each hostConnect implementation is configured either to always return this field or never to return it.
CancelDeleteStatusStringD if the service line can be deleted, C if it can be cancelled, blank if neither is possible.
CanUpdateBooleanTrue if an AmendRemarks request can be made on this service line.
CanAcceptBooleanTrue if an AcceptService request can be made on this service line.
PriceCodeString (2)Price code of rates used on this service line. Optional. This field is not available at some hostConnect sites (depends on configuration settings in hostConnect).
RemarksStringGeneral remarks field (see note 1 for  AddService ).
LinkedServiceLineIdIntegerNon-zero if this service is related to another service in the booking, and neither are involved in a package. Currently only use is for the return of services booked via a third-party provider or a fixed service. In product like externally sourced air the field is used to identify each sector of the flight
StatusStringThe inventory status of the service line. See the description of the Status return value for the  AddService  request for more information. Status is only returned for services lines within confirmed bookings (not those within quotes).
HeaderServiceLineIdIntegerIf this service line is a part of a package, then this field gives the service line id of the package header.
SubServiceLineIdIntegerIf this service line is a package header service line that has additional service lines associated with it then there is a SubServiceLineIds element returned, that contains one or more SubServiceLineId elements, each of which is the service line id of a service line associated with the package.
CancelPenaltyXML elementEach  CancelRule  element contains  CancelHours,  LinePrice,  AgentPrice  and  SellPrice. For each of  AgentPrice  and  SellPrice, it is only returned if the corresponding field is returned for the service line.
CancelPenaltyServiceLineIdIntegerReturned if this service line has had a cancel penalty created for it, and is the service line id of the cancel penalty service line.
CancelledServiceLineIdIntegerReturned for a cancel penalty service line to identify the service line it was created for.
LocationCodeStringLocation code the service line was booked under.
SequenceNumberInteger (1..5)Number identifying a particular extra
QuantityIntegerThe quantity of one extra included in the service line.
Description
IsPricePerPerson
ChargeBasis
IsCompulsory
 Additional information about an extra (see the  OptionInfo  section for details of these elements). These fields are returned unless the service line option is not accessible via hostConnect.
ExtSupplierIdStringThe identifier for the supplier used in the external system.
ExtOptionIdStringThe identifier for the option used in the external system.
ExtOptionDescrStringOption description used in the external system.
ExtRatePlanCodeStringThe external system's rate plan code for the rate returned.
ExtRatePlanDescrStringDescription of the rate plan code.
CancelPoliciesAdditionalDetailsXML elementsSee the  OptionInfo  section for details of these elements.

2.9   PriceBooking   (deprecated)

This request returns price information for the specified booking. The currency used is the currency associated with the specified agent. The units of the prices returned is "dollars".

Note that this request is now deprecated. The total price of a booking is now available via  GetBooking .

2.10   SetBookingRemarks

Associated with each booking is a general-purpose remarks field. Unlike most other booking-related fields, this field cannot be set in the  AddService  request (though its value is returned by    GetBooking ). Instead, it must be set using the  SetBookingRemarks  request. The existing value in the remarks field is overwritten.

Input data items

AgentID  Passwordbooking identifier. Also:

Data itemTypeDescription
RemarksString (60000)The remarks being recorded. Required.

Output data items

On success, an empty response message is returned.

2.11  GetBookingMessage

This request retrieves the specified Tourplan message generated for the specified booking. The message types available, and the format of each message type are site-specific.

Input data items

AgentID  Passwordbooking identifier. Also:

Data itemTypeDescription
MessageLabelStringA message label returned by GetSystemSettings (must be a quote label if the booking specified is a quote, otherwise must be a booking label).
OutputFormatStringFormat that the message is returned in. One of txt (plain text), pdf, html or docx. Optional (defaults to html).

Output data items

Data itemTypeDescription
OutputFormatStringFormat that the message is returned in. One of txt (plain text), pdf, html or docx.
MessageStringThe message generated from the specified booking using the specified message template. Note that if the output format is pdf or docx then the contents of this field are encoded in base64 format.

2.12  Resequence

The sequence numbers assigned to the various service lines play a part in determining the order of service lines in Tourplan messages. Service lines appear in increasing date order. The order of service lines on the same date is determined by the sequence numbers of those service lines. The   Resequence   request provides a way to change the sequence number order of the service lines in a booking. A list of two or more service line ids is given. The sequence numbers of the service lines listed are changed so as to make the order of the service lines in the booking match the order specified. Note that it is an error for the order given to not match the date order of the service lines. The request might list all service lines in the booking, although this is not required. Note that any service line not listed in the input may or may not have its sequence number changed, and may appear in any order with respect to any other service lines on the same day.

The request returns the sequence numbers of all service lines in the booking.

Input data items

AgentID  Passwordbooking identifier. Also:

Data itemTypeDescription
ServiceLineIdIntegerService line identifier. In fact multiple service line identifiers can be specified (at least two are required) by having a series of ServiceLineId elements within a NewSequence element.

Output data items

Details are returned of the current sequence numbers of all service lines in the booking (not just the ones specified in the request). A   LineSequenceNumbers   element contains details of all service line identifiers and sequence numbers, each pair of which is within a   LineSequenceNumber element.

Data itemTypeDescription
ServiceLineIdIntegerService line identifier.
SequenceNumberIntegerThe sequence number of the service line (which may or may not have been changed by the request).

2.13 AddDialogueEntry

Associated with each booking is a dialogue containing entries submitted externally via iCom from agents, and entries submitted internally via Tourplan for viewing by agents. This request adds a new entry to the dialogue.

Input data items

AgentID  Passwordbooking identifier. Also:

Data itemTypeDescription
DialogueEntryString (1500)The new dialogue entry. Required.

Output data items

Data itemTypeDescription
DialogueStringThe contents of the dialogue after the new entry has been added.

2.14  GetLocations

The   GetLocation   request returns a list of all location codes and names used in the system. Note that each   Opt   option identifier contains a location code.

Input data items

AgentID  Password.

Output data items

  Locations   element contains details of all locations, each pair of which is within a   Location   element.

Data itemTypeDescription
CodeString (3)The location code.
NameStringThe location name.

2.15  GetServices

The   GetServices   request returns a list of all service codes and names used in the system. Note that each   Opt   option identifier contains a service code.

Input data items

AgentID  Password.

Output data items

  TPLServices   element contains details of all service codes and names, each pair of which is within a   TPLService   element.

Data itemTypeDescription
CodeString (2)The service code.
NameStringThe service name.

2.16  SupplierInfo

The   SupplierInfo   request returns details of one or more suppliers.

Each supplier has two unique identifiers: its supplier code and its supplier number. Of the two, the supplier number is much less likely to change over time, and so is the best choice as the primary form of supplier identification in a system using hostConnect to interact with a Tourplan system. The supplier code will very likely change if the supplier name changes, and supplier name changes are not uncommon.

Suppliers are specified to the   SupplierInfo   request as zero or more supplier codes and zero or more supplier numbers (at least one supplier code or supplier number must be specified).

Input data items

AgentID  Password. Also:

Data itemTypeDescription
SupplierCodeString (6)

Tourplan supplier code. Zero or more supplier codes are to be specified.

pattern is a supplier code that contains one or more   ?   characters. When a pattern is specified it is checked against all supplier codes, and details about those that match the pattern are returned.

SupplierIdIntegerTourplan supplier number. Zero or more supplier numbers are to be specified.
NoteCategoryString (3)If specified then only notes with this category are returned (otherwise all note categories are returned).
NoteFormatStringFormat to return notes in. One of T (plain text returned) or H (HTML returned). Optional (defaults to plain text).
NotesInRtfStringDeprecated (has been replaced by  NoteFormat). Format to return notes in. One of N (plain text returned), Y (plain text returned; it was formerly used to ask for RTF, but that format is no longer supported) or H (HTML returned). Optional (defaults to plain text).
InfoString (1)L for replicated location information, location codes only
P for replicated location information with location codes and pickup points.
LocationCodeString (3)Specifies that only SupplierLocations matching this code should be returned (if a LocationCode is supplied then Info is treated as containing P, but restricted to the location specified).

Output data items

  Suppliers   element contains details of all suppliers, with details for each supplier within a   Supplier   element.

A supplier has zero or more notes, each of which has a category and the actual text of the note.

A supplier has zero or more FYI messages, each of which applies over a certain period. An FYI can be used for recording when renovations will be done at a hotel, for example. Details of each FYI stored in a   FYI   element.

A supplier has zero or more amenities (for a hotel amenities might include swimming pool and broadband internet). For each amenity there is a category, an optional code, a description and a level indicator. Details of each amenity are stored in an   Amenity   element.

A supplier has zero or more   SupplierLocation   elements (depending on what is set in the   Info   input string). A   SupplierLocation   is made of up a location code and zero or more   PickupPoints   elements (whether pickup points are returned is determined by the   Info   input string). More detail on the  SupplierLocation  element is provided in the   OptionInfo   section.

Data itemTypeDescription
SupplierIdIntegerSupplier number.
CodeString (6)The supplier code.
NameStringThe supplier name.
LastUpdateTimestampThe time of the most recent change to information on this supplier.
Address1
Address2
Address3
Address4
Address5
PostCode
StringThe supplier's address.
SupplierAnalysis1 to
SupplierAnalysis6;  SupplierAnalysisDescription1 to
SupplierAnalysisDescription6
StringThe supplier analysis codes and descriptions. Tourplan has 6 supplier analysis codes. Configuration settings determine which (if any) are returned by hostConnect.
PhoneStringSupplier phone number (XML element is omitted if blank). Phone numbers are available if returning of supplier contact details is enabled.
FaxStringSupplier fax number (XML element is omitted if blank). Fax numbers are available if returning of supplier contact details is enabled.
EmailStringSupplier email address (XML element is omitted if blank). Email addresses are available if returning of supplier contact details is enabled.
WebStringSupplier web page URL (XML element is omitted if blank). Web page URLs are available if returning of supplier contact details is enabled.
NoteCategoryStringThe note category code (the type of note this is).
NoteTextStringThe contents of the note.
LastUpdateTimestampWhen the note was last changed.
DateFromDateThe start of the period of an FYI.
DateToDateThe end of the period of an FYI.
FYITextStringThe FYI message.
AmenityLevelStringS for a supplier amenity and O for an option amenity (SupplierInfo always returns supplier level amenities; OptionInfo can return supplier and option level amenities).
AmenityCodeStringAmenity code (for standard amenities). Amenities codes differ from Tourplan system to Tourplan system.
AmenityCategoryStringAmenity category. Amenities categories differ from Tourplan system to Tourplan system.
AmenityDescriptionStringTextual description of the amenity.
SupplierLocation Code and List of PickupPoints

2.17  ListBookings

The   ListBookings   request returns header-level details of zero or more bookings made by the specified agent, and that meet all of the criteria specified. If a sub-login is supplied then only details of bookings associated with that sub-login are returned.

Input data items

AgentID  Password. Also:

Data itemTypeDescription
TravelDateFromDateOnly details for bookings that travel on or after this date are returned. Optional.
RefStringOnly details for the booking with this booking reference are returned. Optional.
BookingIdIntegerOnly details for the booking with this booking id are returned. Optional.
TravelDateToDateOnly details for bookings that travel on or before this date are returned. Optional.
EnteredDateFromDateOnly details for bookings created on or after this date are returned. Optional.
EnteredDateToDateOnly details for bookings created on or before this date are returned. Optional.
NameContainsStringOnly details for bookings whose booking name contains this string are returned. Optional.
AgentRefStringOnly details for bookings whose agent reference equals this string are returned. Optional.
CurrencyStringOnly details for bookings in this currency are returned. Optional.
BookingTypesStringIf A then details of all bookings are returned, including group book bookings. Access to group book bookings has been provided to give access to accounting information on group book bookings. It is not possible to call GetBooking for a group book booking. Also, it is not possible to change a group book booking in any way. Optional.

Output data items

  BookingHeaders   element contains details of bookings, with details for each booking within a   BookingHeader   element.

The fields returned are a subset of those returned in  

  GetBooking:    BookingId  Ref  Name  QB  Consult  AgentRef  TravelDate  EnteredDate  BookingStatus  BookingType  IsInternetBooking  Currency,    TotalPrice,  AgentPrice   and   AccountingDetails.

Note that use of   TotalPrice  and  AgentPrice   is deprecated, as occasionally it can return 0 instead of the actual price (use   GetBooking   to get this information).

2.18  GetAgentSublogins

The   GetAgentSublogins   request returns a list of all sub-logins associated with the specified agent login. If the login is the main agent login then details of all sub-logins for that agent are returned. If the login is a sub-login then only details for that sub-login are returned.

Input data items

AgentID  Password.

Output data items

  Sublogins   element contains details of all sub-logins, with details for each sub-login within a   Sublogin   element.

Data itemTypeDescription
AgentIDStringThe sub-login code.
NameStringThe name associated with this sub-login.
TitleString (10)A title associated with this sub-login (optional).
ForenameString (60)The forename name associated with this sub-login (optional).
SurnameString (60)The surname name associated with this sub-login (optional).
Address1String (60)The first of up to 5 address lines that can be associated with this sub-login (optional).
Address2String (60)The second of up to 5 address lines that can be associated with this sub-login (optional).
Address3String (60)The third of up to 5 address lines that can be associated with this sub-login (optional).
Address4String (60)The forth of up to 5 address lines that can be associated with this sub-login (optional).
Address5String (60)The fifth of up to 5 address lines that can be associated with this sub-login (optional).
PostCodeString (20)The post code for the address that can be associated with this sub-login (optional).
ContactPhoneString (40)The contact phone number that can be associated with this sub-login (optional).
MobilePhoneString (40)The mobile phone number that can be associated with this sub-login (optional).
FaxString (40)The fax number that can be associated with this sub-login (optional).
EmailString (60)The email address that can be associated with this sub-login (optional).
Indicator1BooleanA user-defined boolean field that can be associated with this sub-login (optional).
Indicator2BooleanA user-defined boolean field that can be associated with this sub-login (optional).
Indicator3BooleanA user-defined boolean field that can be associated with this sub-login (optional).

2.19  AddAgentSublogin

The   AddAgentSublogin   request adds a new sub-login for the specified agent (note that the AgentID supplied must be that of the main agent login).

Input data items

AgentID  Password. Also:

Data itemTypeDescription
AgentSubloginStringThe new sub-login code (whose prefix must match the AgentID in this request). No more than 30 characters are allowed after the prefix. Required.
AgentSubPasswordString (20)The password for the new sub-login (required).
NameString (40)The name associated with the new sub-login (required).
TitleString (10)A title associated with the new sub-login (optional).
ForenameString (60)The forename name associated with the new sub-login (optional).
SurnameString (60)The surname name associated with the new sub-login (optional).
Address1String (60)The first of up to 5 address lines that can be associated with the new sub-login (optional).
Address2String (60)The second of up to 5 address lines that can be associated with the new sub-login (optional).
Address3String (60)The third of up to 5 address lines that can be associated with the new sub-login (optional).
Address4String (60)The forth of up to 5 address lines that can be associated with the new sub-login (optional).
Address5String (60)The fifth of up to 5 address lines that can be associated with the new sub-login (optional).
PostCodeString (20)The post code for the address that can be associated with the new sub-login (optional).
ContactPhoneString (40)The contact phone number that can be associated with the new sub-login (optional).
MobilePhoneString (40)The mobile phone number that can be associated with the new sub-login (optional).
FaxString (40)The fax number that can be associated with the new sub-login (optional).
EmailString (60)The email address that can be associated with the new sub-login (optional).
Indicator1BooleanA user-defined boolean field that can be associated with the new sub-login (optional).
Indicator2BooleanA user-defined boolean field that can be associated with the new sub-login (optional).
Indicator3BooleanA user-defined boolean field that can be associated with the new sub-login (optional).

Output data items

On success, an empty response message is returned.

2.20  UpdateAgentSublogin

The   UpdateAgentSublogin   request modifies the password of the main login or the password and associated details of an existing sub-login. Modification of the details of the main agent is not permitted. If the AgentID supplied is the main login then the main login or any of that agent's sub-logins can be modified. If the the AgentID supplied is a sub-login then only that sub-login can be modified.

Input data items

AgentID  Password. Also:

Data itemTypeDescription
AgentSubloginStringThe sub-login to be modified.
AgentSubPasswordString (20)The new password (optional).
NameString (40)The new name for the sub-login (optional).
TitleString (10)A title associated with this sub-login (optional).
ForenameString (60)The forename name associated with this sub-login (optional).
SurnameString (60)The surname name associated with this sub-login (optional).
Address1String (60)The first of up to 5 address lines that can be associated with this sub-login (optional).
Address2String (60)The second of up to 5 address lines that can be associated with this sub-login (optional).
Address3String (60)The third of up to 5 address lines that can be associated with this sub-login (optional).
Address4String (60)The forth of up to 5 address lines that can be associated with this sub-login (optional).
Address5String (60)The fifth of up to 5 address lines that can be associated with this sub-login (optional).
PostCodeString (20)The post code for the address that can be associated with this sub-login (optional).
ContactPhoneString (40)The contact phone number that can be associated with this sub-login (optional).
MobilePhoneString (40)The mobile phone number that can be associated with this sub-login (optional).
FaxString (40)The fax number that can be associated with this sub-login (optional).
EmailString (60)The email address that can be associated with this sub-login (optional).
Indicator1BooleanA user-defined boolean field that can be associated with this sub-login (optional).
Indicator2BooleanA user-defined boolean field that can be associated with this sub-login (optional).
Indicator3BooleanA user-defined boolean field that can be associated with this sub-login (optional).

Output data items

On success, an empty response message is returned.

2.21 DeleteAgentSublogin

The   DeleteAgentSublogin   request removes a sub-login for the specified agent (note that the AgentID supplied must be that of the main agent login for the agent whose sub-login is being deleted).

Input data items

AgentID  Password. Also:

Data itemTypeDescription
AgentSubloginStringThe sub-login code for the sub-login being deleted (required).

Output data items

On success, an empty response message is returned.

2.22 AmendServiceRemarks

Request that a one of more of the remarks fields of a service line be updated.

Input data items

AgentID  Passwordbooking identifier. Service lines are identified as per  DeleteService  (using   ServiceLineId, or   Date   and   SequenceNumber  ). The following data items are permitted (all are optional; see  AddService  for field details):   puTime  puRemark  doTime  doRemark  Remarks.

Output data items

None.

2.23 GetSystemSettings

The   GetSystemSettings   request returns information about the overall system settings.

Input data items

AgentID  Password.

Output data items

The information returned consists of a number of simple fields, a   Countries   element that contains details of each country (its name, and a list of destinations within the country), an   AvailableMessages   element containing a list of the names of the standard iCom messages available, and a   BookingStatuses   element that lists the valid non-blank   BookingStatus values (blank is often a possible value, but is not returned in this list of booking statuses).

Data itemTypeDescription
QuotesEnabledBooleanSpecifies whether it is possible to create quotes using AddService. If true both quotes and bookings can be created; if false only bookings can be created.
QuotesAreDefaultBooleanSpecifies whether webConnect should default to creating quotes or creating bookings. Only relevant if quotes are enabled.
QuoteMessageLabelStringLabel of one of the standard messages that can be retrieved for a quote (by passing the label as MessageLabel in a GetBookingMessage request).
BookingMessageLabelStringLabel of one of the standard messages that can be retrieved for a booking (by passing the label as MessageLabel in a GetBookingMessage request).
IsAgentDialogueEnabledBooleanTrue if AddDialogueEntry requests are permitted; false if they are not.
CountryNameStringName of a country. Often multiple countries are not defined, in which case all destination names are returned within the country (Unspecified).
DestinationNameStringName of an iCom destination. One technique for searching for options with the OptionInfo request is based on specifying a (DestinationName,  ButtonName) pair.
BookingStatusStringA booking status that can be returned by GetBooking or ListBookings.

2.24 GetServiceButtons

The   GetServiceButtons   request returns a list of all service buttons names.

Input data items

AgentID  Password.

Output data items

  ButtonNames   element is returned that contains   ButtonName  elements.

Data itemTypeDescription
ButtonNameStringName of an iCom service button. One technique for searching for options with the OptionInfo request is based on specifying a (DestinationName, ButtonName) pair.

2.25 GetServiceButtonDetails

The   GetServiceButtonDetails  request  returns information on the specified service button. Service buttons are primarily a way of grouping options for searching purposes (using   OptionInfo), but also have some influence on how service options are booked (the various remarks fields that are accepted, for example).

This request was added to support Tourplan webConnect, and many of the fields returned are likely to be of little interest to other hostConnect users.

Input data items

AgentID  Password. Also:

Data itemTypeDescription
ButtonNameStringThe name of the iCom service button whose details are required. Required.
DestinationNameStringThe name of the iCom service button whose details are required. If this field is specified then additional information is returned about the specified destination in the specified service button.

Output data items

Two groups of data items are returned. One group is always returned. The second group is returned only if   DestinationName   is specified in the input.

Data items always returned

The information returned consists of a number of simple fields, a   Countries   element (whose structure is the same as for the   GetSystemSettings   request) and a   RemarksDetails   element that contains details of which remarks fields can be entered for service options associated the service buttons, and screen labels to use.

Data itemTypeDescription
ScuPromptStringIf it is recommended that OptionInfo requests for this service button include SCUqty (or DateTo) the ScuPrompt is returned and is the screen label to use for the quantity field (such as Night(s) for an Accommodation service button. Optional.
RoomBasedBooleanTrue if service options for this service button are predominantly room-based.
ClassLabelStringScreen label to use when displaying classes for this service button. It might be Star rating for an accommodation service button, or Vehicle type for a car rental service button.
DisplayOptionsWithZeroRatesBooleanIf true then it is recommended that options with no rates should still be displayed (intended for use by Tourplan webConnect).
PickupLabelStringScreen label to use for AddService fields puTime and puRemark for this service button.
PickupTimeAllowedBooleanIs entry of AddService field puTime allowed for this service button.
PickupRemarksAllowedBooleanIs entry of AddService field puRemark allowed for this service button.
DropoffLabelStringScreen label to use for AddService fields doTime and doRemark for this service button.
DropoffTimeAllowedBooleanIs entry of AddService field doTime allowed for this service button.
DropoffRemarksAllowedBooleanIs entry of AddService field doRemark allowed for this service button.
RemarksLabelStringScreen label to use for AddService field doRemarks for this service button.
RemarksAllowedBooleanIs entry of AddService field Remarks allowed for this service button.
CountryName
DestinationName
String
String
Countries elements (containing these fields) is returned. Names of destinations with no options linked to the service button are not returned. Likewise, the names of countries with no options linked to the service button are not returned.
Data items returned when DestinationName  is supplied

If there are no options found with the   ButtonName  DestinationName   specified in the input, then the   LocalityDescriptions,  ClassDescriptions  and  CodeTables   elements are not returned.

Data itemTypeDescription
DestinationNameStringThe DestinationName supplied in the request.
LocalityDescriptionStringLocality descriptions are returned in a LocalityDescriptions element. These are the localities used by the options associated with the service button and destination combination specified in the input.
ClassDescriptionStringZero or more class descriptions are returned in a ClassDescriptions element. These are the classes used by the options associated with the service button and destination combination specified in the input.
CodeTableTypeStringIf there are one or more options for the specified service button / destination combination, and hostConnect is configured to return one or more of the database or supplier analysis codes, then a  CodeTables  element is returned containing one or more code tables (each code table is returned in a  CodeTable  element). Each code table has a  CodeTableType  that specifies which code table the entries are from. Valid values are DB1 (database analysis code 1) to DB6, and CR1 (supplier analysis code 1) to CR6.
Code,  DescriptionStringsFor each code table returned there is a  CodeTableEntries  element containing one or more  CodeTableEntry  elements. Each  CodeTableEntry  element contains a  Code  value and its  Description.

2.26  AcceptService

Accept an optional service line. An optional service line is one that does not cost into the booking (  CostedInBooking   is returned as   Y  ). If   CanAccept   is returned as   Y   then hostConnect can be told (via this request) that the service line is accepted. This has the effect of changing the status of the service to confirm the user's interest, and to add the service line total in to the booking total. This can be used for optional package components, or where a hotel stay has been added to a booking in an optional way because the originally requested hotel was not available.

Input data items

AgentID  Passwordbooking identifier. Service lines are identified using   ServiceLineId.

Output data items

None.

2.27  UpdateBooking

This request allows some of the booking-level fields that can be set using   AddService   to be updated (see  AddService  for field details). These fields are optional, and only those specified are changed.

Input data items

AgentID  Passwordbooking identifier  Consult  AgentRef  Email.

2.28  GetSupplierServiceLines

This request gives a supplier access to service lines booked with that supplier. Only service lines that meet  all  of the specified filters are returned.

Input data items

Password. Also:

Data itemTypeDescription
SupplierLoginStringThis request requires a supplier login, rather than an AgentId
GetForChainBooleanIf false (the default), the service lines returned are those for the supplier whose login is SupplierLogin. If true, the service lines returned are those for the suppliers whose Master Supplier is the supplier whose login is SupplierLogin.
Opt
OptionNumber
String
Integer
It is possible to restrict service lines to just those for a particular option (identified by option code or option number). If an option code is supplied then the location code can be either the actual location code, or a replicated location. If the former, then all service lines for the option are returned. If the latter, then only service lines with a matching replicated location are returned.
TravelDateFromDateOnly return details of service lines whose Date is on or after TravelDateFrom. Optional.
TravelDateToDateOnly return details of service lines whose Date is on or before TravelDateTo. Optional.
EnteredDateFromDateOnly return details of service lines created on or after EnteredDateFrom. Optional.
EnteredDateToDateOnly return details of service lines created on or before EnteredDateTo. Optional.
TourplanServiceStatusStringOne or more TourplanServiceStatus elements can be supplied in a TourplanServiceStatuses element. If one or more TourplanServiceStatus values are given then only service lines whose status is one the the states supplied are returned. Optional.
ServiceLineIdIntegerIf  ServiceLineId  is supplied then only service lines with the specified id are returned. This means either one service line is returned (if it exists, and meets any other filter criteria specified) or no service lines are returned.  Optional.

Output data items

One or more   SupplierServiceLine   elements are returned in a   SupplierServiceLines   element (if there are no service lines then no   SupplierServiceLines   element is returned). Most of the elements returned in a   SupplierServiceLine   are also returned in by   GetBooking. Refer to the GetBooking documentation for information on these fields. The remaining fields are documented below.

Data itemTypeDescription
BranchNameStringName of the branch making the booking.
DepartmentNameStringName of the department making the booking
AgentCodeStringCode of the agent making the booking.
AgentNameStringName of the agent making the booking.
UDText1  to  UDText5StringBooking user defined text fields, numbered 1 through to 5
TourplanConsultantNameStringName of the consultant managing the booking
TourplanConsultantEmailStringEmail address of the consultant managing the booking.
SupplierCodeStringTourplan supplier code.
SupplierIdIntegerTourplan supplier number.
EnteredDateDateData service line was created.
Adults
Children
Infants
IntegerThe numbers of adults, children and infants booked on the service line, totalled across all rooms.
SingleCountTwinCount,
DoubleCountTripleCount,
QuadCountOtherCount
IntegerThe numbers of each room type booked on the service line.
TourplanServiceStatusStringTourplan status if the service line.
PriceCodeStringPrice code used in the service line.
CostCurrencyStringCurrency code of cost amount.
CostExclusiveIntegerCost of the service line (in cents) exclusive of tax. To get the inclusive amount add CostExclusive and CostTax.
CostTaxIntegerTax component of cost.

2.29  SupplierUpdateServiceLines

This request allows a supplier limited edit access to service lines booked against their product.

Input data items

Password. Also:

Data itemTypeDescription
SupplierLoginStringThis request requires a supplier login, rather than an  AgentId
SupplierUpdateServiceLinesXML elementThis is a collection of the SupplierUpdateServiceLine elements that describe the service lines to manipulate and the changes required.
The SupplierUpdateServiceLines group

This group contains the list of manipulations to perform where each SupplierUpdateServiceLine element identifies a service line and the related changes.

Password. Also:

Data itemTypeDescription
ServiceLineIdIntegerThe ID of the service line to be manipulated.
SupplierConfirmationStringThe new supplier confirmation code that should be applied to the service line, not changed if not supplied.
TourplanServiceStatusStringThe new service status that should be applied to the service line, not changed if not supplied.

Output data items

One or more  ServiceLineId  elements are returned in a  SupplierUpdatedServices  element, one ID per line that was updated. The  SupplierUpdatedServices  element will not be present if no updates were made.

One or more  SupplierFailedServiceUpdate  elements are returned in a  SupplierFailedServiceUpdates  element, one entry per line that failed to update.

Data itemTypeDescription
SupplierUpdatedServicesXML elementA list of service lines that were updated.
SupplierFailedServiceUpdatesXML elementA list of service lines that failed to update.
The SupplierFailedServiceUpdates group

This group contains the list of service line updates that failed along with the reason for the failures. Each entry detailing one line that failed to update.

Data itemTypeDescription
ServiceLineIdIntegerThe ID of the service line that failed to update.
UpdateFailureCodeStringThe code that identifies the reason for failure.
UpdateFailurereasonStringThe error message that describes the reason for the failure.  

2.30  GetProductSearchData

This request provides all data needed to support product search. The data is available from other requests (GetLocations, GetSystemSettings, GetServiceButtons, GetServiceButtonDetails). The reason for adding GetProductSearchData is that it enables a client to make a single request to get back data that might require hundreds of requests using the original set of requests.

Input data items

AgentId,  Password.

Output data items

There are three top level elements in the reply:  CodeTables,  CountryList  and  ServiceButtons. Each is explained in a section below.

The  CodeTables  element
Data itemTypeDescription
CodeTableTypeString

The  CodeTables  element returned contains a number of code tables (each code table is returned in a  CodeTable  element). Each code table has a  CodeTableType  that specifies which code table the entries are from. Valid values are:

  • LOC: locations
  • LCL: localities
  • CLS: classes
  • CTR: countries
  • DST: destinations
  • DB1 to DB6: database analysis codes 1 to 6
  • CR1 to CR6: supplier analysis codes 1 to 6

Which of the DB and CR tables are present (if any) is determined by system configuration. Also, empty code tables are omitted.

Code,  DescriptionStringsFor each code table returned there is a  CodeTableEntries  element containing one or more  CodeTableEntry  elements. Each  CodeTableEntry  element contains a  Code  value and its  Description.
The  CountryList  element
Data itemTypeDescription
CountryCodeStringDetails for a country are returned in a  CountryInfo  element.  CountryCode  identifies which country the information in a  CountryInfo  element is for.
DestinationCodeStringA  CountryInfo  element contains  DestinationCode  elements, each of which contains the code of a destination in the country.
The  ServiceButtons  element
Data itemTypeDescription
ServiceButtonXML elementA  ServiceButton  element is returned for each service button. The  ButtonCountries  child element contains details of codes used in options associated with the service button. The remaining fields are covered in the  GetServiceButtonDetails documentation
CountryCodeStringCode lists are returned for each destination, and destination are grouped by country. This field identifies a country.
DestinationCodeStringIdentifies a destination.
CodeTableTypeStringFor each destination, details of a number of code tables are resturned. This field identifies which code table a list of codes is for.
CodeStringAn code value that is used in at least one option, that is linked to the relevant service button / destination combination.

 

Tourplan Pacific Ltd reserves the right to change, modify, add or remove portions of this interface at any time.