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

Interface Definition for Tourplan productConnect

Version: 3.10.000
Date: 2015-02-26

1 Overview

Tourplan productConnect is designed to make external tools able to create, update and retrieve location, agent, supplier and product information (service options, rates and inventory) in Tourplan. This document details the interface provided by productConnect (the detailed Tourplan knowledge that underlies decisions on how best to setup data in Tourplan is outside the scope of this document).

This section gives an overview of the interface. The overview comprises details of changes in this version, an introduction to the format of request and reply messages, details of the various data types used for values specified in request and reply messages and a discussion of some data items that appear in several messages.

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 the previous version:

  1. The HTTP header Accept-Charset is now acted on if it is supplied to productConnect.

1.2 Formats for requests and responses

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. 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 all cases the reply message is text/xml.

A DTD specifies the formats of XML documents sent and received by productConnect. Each XML document sent to productConnect has a Request root element, and each XML document sent by productConnect has a Reply root element. The Request element contains a single element whose name is the name of a productConnect request concatenated with the string Request. An analogous situation exists for XML documents sent by productConnect in reply.

If the Accept-Charset HTTP header is present, it determines the character set encoding of the reply. If the header is not present, or has a value of *, then the encoding used is UTF-8.

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

Each data item is stored as an XML element (element 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, Decimal, Boolean, Date, Time. The following points clarify how values of these data types are represented.

  • Some fields can include patterns. Generally these are code fields specifying which options, suppliers, or agents (for example) should have their details returned. At present the ? is the only character with special meaning (it matches any individual character). The ?????? pattern for a supplier code matches all supplier codes. The SYD??? supplier code pattern matches all supplier codes that have SYD as the first three characters.
  • 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.
  • 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.
  • All decimal numbers output have 4 decimal places.

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.

General items

Data itemTypeDescription
UserStringMaster login for the Database Interface.
PasswordStringMaster password for the Database Interface.
RequestIdStringThis is an attribute of the Request element. If specified it is included in log messages recorded for this request.

Supplier login and password can be used for the requests: GetLocation, GetSupplier, GetOption, SetRate, GetRate, SetInventory, GetInventory, ChangeSupplier and ChangeOption. GetLocation gives access to all locations (as it does if the master login is used). For all of the other requests, where a supplier login is used only the supplier details, options (including rates) and inventory of that supplier can be accessed. For requests that accept wildcards (such as GetSupplier and GetOption), searches are limited to the supplier and option details for the supplier whose login details have been given.

Note records

Various entities in Tourplan (such as suppliers and options) can have notes. Multiple notes are permitted, each with a different category (which must be of the correct category type: DB for option notes, for example). For each note specified, if a note of the specified category does not exist then one is created. Otherwise the current note is replaced. At present note categories that allow multiple notes are not supported.

Data itemTypeDescription
CategoryString (3)A note category (of an appropriate category type) that has been setup in Tourplan.
Message_TextStringThe contents of the note in plain text (in which case productConnect converts them to RTF) or in RTF.

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, productConnect produces either an ordinary reply (of a type that matches the request, as detailed below) or an error reply, in which 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.

2.1 Ping

The Ping request is provided as a simple way of determining whether the Database Interface is alive.

Input data items

None.

Output data items

Data itemTypeDescription
VersionStringproductConnect version details.

2.2 AddLocation

The AddLocation request adds a new location to the Tourplan database.

AddLocation has no outputs.

Input data items

User, Password, plus the following.

Data itemTypeDescription
CodeString (3)Location. Required.
NameString (40)Location name. Required.

2.3 ChangeLocation

The ChangeLocation request has the same inputs as AddLocation.

ChangeLocation has no outputs.

Retrieves details of a Tourplan location. Inputs are User, Password and Code (the code of the location whose details are required). Output data items are the same as the LocationData element accepted by AddLocation and ChangeLocation.

2.5 AddAgent

The AddAgent request adds a new Tourplan agent to the Tourplan database.

Input data items

User, Password. The remaining fields can be broken down into two groups; general agent information, and information on zero or more contacts. These two groups are discussed separately below.

The general group
Data itemTypeDescription
DefaultAgentStringA new agent is created by copying an existing agent and then changing it as per the new values supplied in the AddAgent request. DefaultAgent is the code of the agent to be copied. Required.
AgentCodeString (6)Code to be given to the new agent (an error is returned if there is already an agent with this code). Required.
NameString (60)Agent name. Optional.
Address1 to Address5String (60)Five address lines. Each is optional.
PCodeString (12)Post code. Optional.
Analysis_Master1 to Analysis_Master6String (2)Agent analysis codes. Each must be a valid code for that particular accounts receivable analysis code. Optional.
IatacodeInteger (0..)Iatacode. Optional.
TaxIndicatorInteger (0 to 8)Tax indicator. Optional.
CommissionDecimal (0..)Commission. Optional.
MarkupDecimal (0..)Markup. Optional.
LanguageString (2)Language code. Must be one of the language codes setup in Tourplan. Optional.
AgencyChainString (6)Agent code that identifies the Master Agent that this agent is associated with. The Master Agent must exist, and must be a master agent. Note that if the agent being added is a master agent then AgencyChain is ignored. Optional.
AgentMasterBooleanIf true then this agent is a master agent. Optional.
Default_CurrencyString (3)Default currency. If specified then Default_Currency must be the code for one of the currencies associated with the agent. At present agent currencies cannot be added via productConnect, and are copies of the currency details for the DefaultAgent. Optional.
DeletedBooleanSpecifies whether the agent is marked as deleted or not. Optional.
Int_AccessBooleanSpecifies whether the agent can login via iCom. Optional.
Int_LoginString (20)The agent's iCom login code. Optional.
Int_PasswordString (20)The agent's iCom password. Optional.
Int_IP_AddressString (60)IP address restrictions in place for this agent. Optional.
Int_BrString (2)Tourplan branch assigned to this agent's iCom bookings (must be a valid Tourplan branch). Optional.
Int_DpString (2)Tourplan department assigned to this agent's iCom bookings (must be a valid Tourplan department). Optional.
Int_SA1 to Int_SA6String (2)Tourplan booking analysis codes assigned to this agent's iCom bookings. Each must be a valid code for that particular booking analysis code. Optional.
UDText1 to UDText10String (60)Ten user-defined text fields.
Created_ByString (30)Who created the agent record.
Edited_ByString (30)Who last edited agent record.
Mailing_NameString (60)Mailing name. Optional.
Mailing_Address1 to Mailing_Address5String (60)Mailing address lines. Each is optional.
Mailing_PCodeString (12)Mailing post code. Optional.
Agent_Price_CodeString (2)Zero or Agent_Price_Code values can appear within a Price_Codes element. Each must be a valid agent price code. Note that if there is no Price_Codes element then the existing price codes are not changed; if there is a Price_Codes element then the existing price codes are replaced by the zero or more price codes supplied. Optional.
Split_CodeString (15)Zero or Split_Code values can appear within an Allotments element. Each must be a valid split code. Note that if there is no Allotments element then the existing split code list is not changed; if there is an Allotments element then the existing split codes are replaced by the zero or more split codes supplied. Optional.

The ContactInfo group

If contacts are supplied, there are one or more ContactInfo elements within a Contacts element. The following data items are found within each ContactInfo element.

Data itemTypeDescription
Contact_TypeString (2)Must be one of the contact types setup in Tourplan. Required.
Contact_NameString (60)Name of contact. Required.
EmailString (60)Email address. Optional.
FaxString (40)Fax number. Optional.
PhoneString (40)Phone number. Optional.
MobileString (40)Mobile number. Optional.
WebString (60)Web address. Optional.

Output data items

Data itemTypeDescription
Agent_IDIntegerInternal Tourplan identifier for the new agent.

2.6 ChangeAgent

The ChangeAgent request has the same inputs as AddAgent except that DefaultAgent does not apply for ChangeAgent.

ChangeAgent has no outputs.

2.7 GetAgent

Retrieves details of a Tourplan agent. Inputs are User, Password and AgentCode (the code of the agent whose details are required). Multiple agent codes can be given. Also, an agent code can be a pattern.

Output data items are AgentData elements for the specified agent(s).

2.8 AddSupplier

The AddSupplier request adds a new supplier to the Tourplan database.

Input data items

User, Password. The remaining fields are discussed in groups: general supplier information, rate policy, amenities, notes, contacts, FYIs, and replicated locations. The note records must be of categories with category type CR or DS.

General fields
Data itemTypeDescription
DefaultSupplierStringA new supplier is created by copying an existing supplier and then changing it as per the new values supplied in the AddSupplier request. DefaultSupplier is the Tourplan supplier code of the supplier to be copied. Required.
SupplierCodeString (6)Supplier code to be given to the new supplier (an error is returned if there is already a supplier with this code). Required.
DeletedBooleanSpecifies whether the supplier is marked as deleted or not. Optional.
NameString (60)Supplier name. Optional.
Address1 to Address5String (60)Five address lines. Each is optional.
PCodeString (12)Post code. Optional.
Analysis_Master1 to Analysis_Master6String (2)Supplier analysis codes. Each must be a valid code for that particular accounts payable analysis code. Optional.
LanguageString (2)Language code. Must be one of the language codes setup in Tourplan. Optional.
SupplierChainString (6)Supplier code that identifies the Master Supplier that this supplier is associated with. The Master Supplier must exist, and must be a master supplier. Note that if the supplier being added is a master supplier then SupplierChain is ignored. Optional.
SupplierMasterBooleanIf true then this supplier is a master supplier. Optional.
Default_CurrencyString (3)Default currency. If specified then Default_Currency must be the code for one of the currencies associated with the supplier. At present supplier currencies cannot be added via productConnect, and are copies of the currency details for the DefaultSupplier. Optional.
UDText1 to UDText5String (60)Five user-defined text fields.
Mailing_NameString (60)Mailing name. Optional.
Mailing_Address1 to Mailing_Address5String (60)Mailing address lines. Each is optional.
Mailing_PCodeString (12)Mailing post code. Optional.
Int_AccessBooleanSpecifies whether the agent can login via iCom. Optional.
Int_LoginString (20)The agent's iCom login code. Optional.
Int_PasswordString (20)The agent's iCom password. Optional.
Rate Policy
Data itemTypeDescription
Single_Avail to Other_AvailBooleanSpecifies whether each room type is available. Optional.
Single_Ad_Max to Other_Ad_MaxInteger (0..)Specifies for each room type the maximum number of adults that the room can accommodate. Zero means no limit set (in Tourplan) and in iCom it means use the standard capacities (1 for a single, 2 for a twin, and so on). Optional.
Single_Max to Other_MaxInteger (0..)Specifies for each room type the maximum number of adults plus children that the room can accommodate. Zero means no limit set. Optional.
Infant_From, Infant_To, Child_From, Child_To,
Adult_From, Adult_To
Integer (0..)Age ranges for adults, children and infants. If from and to are 0 for a range then it means no particular age range is specified. Age ranges cannot overlap. Optional.
Start_Mon to Start_SunBooleanSpecifies which days of the week a service line can start on. Optional.
Include_Mon to Include_SunBooleanSpecifies which days of the week a service line must include. Optional.
Cross_SeasonString (1)Specifies how a rate is calculated where a rate season boundary is crossed. Must be one of: A (average), F (use rate of first rate period), N (such service lines are not allowed) or S (split the service line on rate season boundaries and cost each independently). Optional.
PickupBooleanSpecifies whether pickup and dropoff details are prompted for. Optional.

Amenities

Each amenity has a code, a category and a description.

Note that currently productConnect returns amenities details but does not update them.

Data itemTypeDescription
AmenityCodeString (6)Amenity code. Is either one of the amenity codes defined in Tourplan, or blank if this is a user-defined amenity.
AmenityCategoryString (3)An amenity category setup in Tourplan.
AmenityDescriptionString (30)Amenity description.

Output data items

Data itemTypeDescription
Supplier_IDIntegerInternal Tourplan identifier for the new supplier.
The FYI group

If FYI details are supplied, there are one or more FYI elements within a FYIs element. The following data items are found within each FYI element.

Data itemTypeDescription
FYI_IDIntegerThe database record number of this FYI record. Returned by GetSupplier requests. Cannot be specified in AddSupplier requests. For ChangeSupplier requests, if FYI_ID is specified then an existing FYI record is to be updated; otherwise a new FYI record is to be created.
Date_AddedDateDate FYI was added. Returned by GetSupplier; cannot be specified in AddSupplier or ChangeSupplier requests.
Date_FromDateThe first day that this FYI message is relevant for. Required for new FYI records, otherwise optional.
Date_ExpiresDateLast day that this FYI message is relevant for. Required for new FYI records, otherwise optional.
Public_MessageBooleanWhether this FYI is visible outside Tourplan. Optional (defaults to false for new FYI records).
Message_TextString (128)The text of the FYI message. If an existing FYI record is being updated and Message_Text is an empty string then the FYI record is deleted. Required for new FYI records (and must not be an empty string), otherwise optional.
The Replicated Location group

Note that at present replicated locations are returned by GetSupplier, but changing them is not supported. If replicated location details are present, there are one or more SupplierLocation elements with a SupplierLocations element. Each SupplierLocation contains a location code, and (optionally) a PickupPoints element containing PickupPoint elements. The following data items are the location code in SupplierLocation and the data items found within each PickupPoint element.

Data itemTypeDescription
CodeStringA Tourplan location code.
Point_IDIntegerThe database identifier of this pickup point.
PointDescriptionStringDescription of this pickup point (Christchurch airport).
CanPickupBooleanAre pickups allowed at this pickup point.
CanDropoffBooleanAre dropoffs allowed at this pickup point.

2.9 ChangeSupplier

The ChangeSupplier request has the same inputs as AddSupplier except that DefaultSupplier does not apply for ChangeSupplier.

ChangeSupplier has no outputs.

2.10 GetSupplier

Retrieves details of a Tourplan supplier. Inputs are User, Password, ConvertNotesToText (an option boolean, default true, that specifies whether notes should be converted to plan text or left as RTF) and SupplierCode (the code of the supplier whose details are required). Multiple supplier codes can be given. Also, a supplier code can be a pattern.

Output data items are SupplierData elements for the specified supplier(s).

2.11 AddOption

The AddOption request adds a new service option to the Tourplan database.

Input data items

User, Password. Apart from DefaultOption, the other input data items can be split into groups, based on XML elements. Each of general data, cost data, voucher data and internet data is a simple list of data items. Enquiry notes contains zero or more enquiry notes of category type DB. See the contact info section in AddAgent for details on how contact information is formatted. Amenities are represented in the same way as for suppliers. Note that only option-level amenities are returned by GetOption (supplier-level amenities are returned by GetSupplier ).

RatePolicyLevel is S or O. If it is S then the supplier rate policy is used as the rate policy of this option. For AddOption and ChangeOption there must be no RatePolicy element supplied if the rate policy level is supplier (for GetOption the supplier rate policy is returned in this case). Otherwise the rate policy level is O and the rate policy element appears and contains the option's rate policy.

Data itemTypeDescription
DefaultOptionString (17)A new option is created by copying an existing option and then changing it as per the new values supplied in the AddOption request. DefaultOption is the 17 character Tourplan location/service/supplier/option code of the option to be copied. Required.
General data
Data itemTypeDescription
OptionCodeString (17)Seventeen character full option code for the new option (it is an error if an option with this code already exists). Characters 1 to 3 must be a location code setup in Tourplan, characters 4 and 5 must be a service code setup in Tourplan and characters 6 to 11 must be a supplier code setup in Tourplan. Required.
Opt_IDIntegerInternal Tourplan option identifier (ignored for AddOption; used in ChangeOption and GetOption).
AcString (1)Option type. Possible values are A (Apartment), F (Flight), I (Itinerary), N (Non-Accommodation), P (Package), Y (Accommodation). At present this field cannot be specified in the AddOption and ChangeOption requests; it is returned by the GetOption request.
DeletedBooleanSpecifies whether the option is marked as deleted or not. Optional.
DescriptionString (60)Option description. Optional.
CommentString (60)Option comment. Optional.
LocalityString (3)Code for a locality that has been setup in Tourplan. Optional.
ClassString (3)Code for a class that has been setup in Tourplan. Optional.
Durationhhhh.mmDuration in hours (0 to 9999) dot minutes (0 to 59). The value specified must contain a dot and values for hours and minutes. Optional.
Analysis1 to Analysis6String (2)Option analysis codes. Each must be a valid code for that particular database analysis code. Optional.
Message_codeString (2)A message format code that has been setup in Tourplan. Optional.
Invoice_text1String (60)Invoice text line 1. Optional.
Invoice_text2String (60)Invoice text line 2. Optional.
Cost data
Data itemTypeDescription
FCUString (6)First charge unit. Common values are person (where charges are per person), room (where charges are per room), vehicle and so on. Optional.
SCUString (6)Second charge unit. What the charge is for. Common values include night (for accommodation services), day (car rental), tour (for a packaged tour), meal (for meals). Optional.
MPFCUInteger (1..999)Maximum pax per first charge unit. Where the first charge unit is some sort of group unit (such as vehicle), then MPFCU specifies the number of pax that can fit in one first charge unit. Ignored (and set to 1) for the Accommodation and Package service categories, and if the first charge unit is person. For the Apartment service category the maximum value is 11. Optional.
PeriodsInteger (0..)Number of 24 hour periods per second charge unit. When producing a voucher this field is used to control production of the out date. If periods is 0, then no out date is produced. Otherwise, periods multiplied by the number of second charge units gives the out date. Basically this field gives the duration of one second charge unit in days. Set to 1 if the SCU supplied is day or night, and to 0 if the SCU supplied is blank. Optional.
Periods_BaseString (1)Basis of the second charge unit. Possible values are D (per calendar day) and P (per 24 hour period). Optional.
Pxb1 to
Pxb24
IntegerSome non-accommodation and package options have rates that depend on the number of pax in the booking. In this case these Pxb values specify the different pax ranges. The first range is for 1 to Pxb1 pax, the second for Pxb1 + 1 to Pxb2 pax, and so on. The final range has a Pxb value of 9999, and this value must appear in the input. Optional.
Child_In_PxbBooleanAre children counted when determining which pax break applies? Optional.
Infant_In_PxbBooleanAre infants counted when determining which pax break applies? Optional.
Ex1 to Ex5String (20)Each option can have up to 5 optional extras defined for it. These five fields give descriptions for these extras (if a description is blank then that particular extra does not exist for this service option). Optional.
ChgEx1 to ChgEx5String (1)Charge basis for extras 1 to 5 (in each case, is only relevant if the matching extra exists). Each must be one of the values F (FCU/SCU), G (Group), P (Person), R (Room), S (SCU), 0 (compulsory pax), 1 (compulsory pax single), 2 (compulsory group), 3 (compulsory group single). Optional.
Ex1Description to Ex5DescriptionString (60)Extended descriptions for extras 1 to 5. Optional.
Int_Hide_Ex1 to Int_Hide_Ex5BooleanFor each extra, is it hidden in iCom? Optional.
Voucher data
Data itemTypeDescription
VnameString (30)Voucher name (appears as the first line of the address in Tourplan's Voucher Details screen). Optional.
Vadd1 to Vadd5String (60)Voucher address lines 1 to 5. Optional.
PCodeString (12)Voucher post code. Optional.
Vtext1 to Vtext10String (60)Voucher text lines 1 to 10. Optional.
EditVtext1 to EditVtext10BooleanAre voucher text lines 1 to 10 editable? Optional.
Internet data

Fields in this section are only relevant if iCom is enabled.

Data itemTypeDescription
Int_OptionBooleanSpecifies whether this option can be accessed using iCom (true) or not (false). Optional.
Int_MoreinfourlString (90)The URL of a web page containing information about this service option. Optional.
Int_Max_AdultsInteger (0..)Max adults (for iCom bookings). Optional.
Int_Max_AdwithchInteger (0..)Max adults with children (for iCom bookings). Optional.
Int_Max_ChildrenInteger (0..)Max children (for iCom bookings). Optional.
Int_Def_AvailString (2)Default inventory for this option where no allocation exists. Values allowed are blank (use the service button default), RQ (put on request), FS (free sale), or NO (not available.
Int_Supplier_AccessBooleanIs this option visible in supplierConnect? Optional.
Int_Sale_FmDateiCom bookings before this date are not accepted. Optional.
Int_Sale_ToDateiCom bookings after this date are not accepted. Optional.

Output data items

Data itemTypeDescription
Opt_IDIntegerInternal Tourplan identifier for the new option.

2.12 ChangeOption

The ChangeOption request has the same inputs as AddOption except that DefaultOption does not apply for ChangeOption. If OptionCode is specified then it identifies the option to change; otherwise Opt_ID identifies the option.

ChangeOption has no outputs.

2.13 GetOption

Retrieves details of a Tourplan option. Inputs are User, Password, ConvertNotesToText (an option boolean, default true, that specifies whether notes should be converted to plan text or left as RTF) and OptionCode (the 17 character option code of the option whose details are required) or Opt_ID. Multiple option codes and/or option ids can be given. Also, each option code can be a pattern.

Output is one or more the OptionData elements.

2.14 SetRate

The SetRate request creates (or replaces) rates for a specified Tourplan option for a specified price code. Any existing rate periods for that option with the same price code that cover part of the period covered by the new rate period are either removed (if they are entirely within the period covered by the new rates) or updated to remove any overlap with the new rate period.

SetRate reports an error if any of the date ranges that would by (fully or partly) replaced contain special rates.

SetRate has no outputs.

Input data items

User, Password. The structure of the DateRange elements is quite complex. In the description below, each sub-section discusses a related group of elements.

DateRange data elements

The simple fields present in the DateRange element are listed in the table below. Each DateRange has one or more RateSet elements. If there is more than one RateSet then each of the RateSet elements must differ in at least the days that they apply or the minimum and maximum SCU values. Also, the Stay_Type values must be different.

Data itemTypeDescription
OptionCodeString (17)The option this set of rates belongs to. OptionCode or Opt_ID must be specified to identify the option.
Opt_IDIntegerInternal Tourplan option identifier. OptionCode or Opt_ID must be specified to identify the option.
Price_CodeString (2)The price code this set of rates belongs to (must be setup in Tourplan). Required.
Date_FromDateThe starting date of the rate period. Required.
Date_ToDateThe closing date of the rate period (must be no earlier than Date_From). Required.
Sale_FromDateThe starting date of the sale period. Required.
Sale_ToDateThe closing date of the sale period (must be no earlier than Sale_From). Required.
SellBeforeTravelIntegerThe number of days or months before travel that a booking must be made. Optional; defaults to 0 (which means no sell before threshold is set).
SellBeforeTypeString (1)The units of SellBeforeTravel. Must be D (for days) or M (for months). Optional; defaults to D.
Buy_CurrencyString (3)Currency the Cost rates are in (must be setup in Tourplan). Required.
Sell_CurrencyString (3)Currency the GroupSell and FITSell rates are in (must be setup in Tourplan). Required.
Exchange_Div_Rate,Exchange_Mut_RateDecimalExchange rate for converting from cost to sell (by dividing or multiplying by the specified rate; only one of the two can be supplied). Note the the exchange rate makes no difference to the rates saved; the exchange rate is simply saved and can be used later within Tourplan to adjust sell rates by adjusting the exchange rate. Optional (only permitted if the buy and sell currencies are different). Values must be greater than 0 and less than 10000.
ChargeExtra1 to ChargeExtra5BooleanIs extra 1 to 5 charged for on a day that is free of charge because of a stay / pay deal? A value for an extra that is not setup for the option is ignored. Optional (default false).
TaxString (3)Tourplan tax codes can be associated with this set of rates by having Tax elements within TaxInfo elements within a Taxes element. Required (the Taxes element is optional, but each TaxInfo supplier must contain a Tax element).
TaxMainOption, TaxSs, TaxTw, TaxTr, TaxQr, 
TaxEx1
, TaxEx2, TaxEx3, TaxEx4, TaxEx5
BooleanPer-component tax flags. Each is optional, and if not specified defaults to true.
RateSet data elements

The simple fields present in the RateSet element are listed in the table below. The format used for the actual rates is covered in the next section.

Data itemTypeDescription
Stay_TypeString (20)Description for this rate set (must be unique amongst the rate sets that belong to a single range). Required..
Rate_TextString (60)Rate text. Optional.
Min_SCU, Max_SCUInteger (1..999)SCU range that this rate set applies to. Optional (defaults are 1 and 999 respectively).
ProvString (1)The rate status. One of C (closed), K (confirmed), M (manual), P (provisional) or T (terminal). Optional (default K).
CommissionableBooleanSpecifies whether the rates in this rate period are commissionable. Optional (default true).
Comm_OrideDecimalOverrides the agent and booking commission. Optional (default 0, which means no override).
PreferInteger (0..)Relative preference of this particular rate. Optional (default 0).
Gross_NettString (1)Either G if gross rates are entered by the user, or N if nett rates are entered. Doesn't affect how rates are stored or interpreted; just how rates are treated in the Tourplan user interface. Optional (default N).
Sell_CodeBooleanTrue if the sell rates used are the sell rates stored in the database; false if the sell rates used are the costs stored in the database. Optional (default true).
Apply_Mon to Apply_SunBooleanSpecifies which days of the week this rate set applies to (at least one must be true). Optional (each defaults to true).
Validate_Min_MaxBooleanIf false then the scu range for a rate set is checked against the SCU of the service line. If true then the scu range for a rate set is checked against the overlap between the service line and the date range. Optional (default false).
Cancel_HoursInteger (0..)Cancellation policy in hours. Any cancellation within this many hours of service date incurs a cancellation penalty. Optional.
Vtext1 to Vtext10String (60)Voucher text lines 1 to 10. Optional (default blank).
EditVtext1 to EditVtext10BooleanCan each of voucher text lines 1 to 10 be changed? Optional (default true).
Stay1 to Stay10
Pay1 to Pay10
Integer (0..)Stay/pay deals that apply to this rate set (stay/pay details can only be specified for options whose value for Periods is 1). If Stay1 is 7 and Pay1 is 5 then there is a stay 7 pay 5 deal for this rate set. Values of 0 for a (stay, pay) pair indicate no stay pay deal for that pair. If N (stay, pay pairs) are supplied then they must be numbered consecutively starting at 1 (Stay1, Pay1) and the values for stay length must increase from Stay1 to StayN. Optional (all default to 0).
Rates

Four groups of rates are specified: group cost rates (in buy currency), FIT cost rates (in buy currency), selling rates for groups (in sell currency) and selling rates for FIT (in sell currency). Each group of rates appears in a Rates element. For apartment options a rate is specified for each different number of adults an apartment can hold. For accommodation options, and for package options without pax break pricing, the main rates are room rates, held in either a RoomRate or a RoomSuppRate element. For options with pax break pricing, rates are stored in a PaxBreakRate element. Otherwise, the main rate is simple stored in the AdultRate element. Child rates can be sent as either a single value in the ChildRate element, or as a collection of values in a ChildBreakRate element (and likewise infant rates can be sent in the InfantRate or InfantBreakRate elements). If neither ChildRate nor ChildBreakRate is supplied then child rates are zero. If ChildRate is supplied then if the option has pax break rates, all pax breaks get the value specified, and if the option does not have pax breaks the sole child rate gets the value specified. Otherwise, If ChildBreakRate is supplied then if the option does not pax break rates the child rate is the rate in the first pax break. If the option does have pax break rates, the values supplied are assigned to the child pax break rates (with 0 assigned to any pax breaks whose rates were not specified).

Data itemTypeDescription
AdultRateDecimalRate per first charge unit (per person, per vehicle, per whatever). Required.
Price_Pxb1 to
Price_Pxb24
DecimalRates for pax breaks 1 through to 24 These elements occur within a PaxBreakRate element. The number of elements supplied must match the number of pax breaks setup within the option.
SG
TW
TR
QD
AA
DecimalRates for the single, twin, triple and quad room types, and for each additional adult. These elements occur within a RoomRate element. Optional.
TS
S1
R3
R4
AA
DecimalRoom rates expressed as twin share, single supplement, triple reduction and quad reduction (and additional adult). These elements occur within a RoomSuppRate element. Optional.
AP1 to AP11DecimalApartment rates. AP1 is the rate for 1 adult, AP2 is the rate for two adults, and so on. If MPFCU is N then values for AP1 to APN should be given.
ChildRateDecimalChild rate/supplement. Optional.
Price_Pxb1 to
Price_Pxb24
DecimalRates for child pax breaks 1 through to 24 These elements occur within a ChildBreakRate element. The number of elements supplied must match the number of pax breaks setup within the option. Zeros are returned.
InfantRateDecimalInfant rate/supplement. Optional.
Price_Pxb1 to
Price_Pxb24
DecimalRates for infant pax breaks 1 through to 24 These elements occur within an InfantBreakRate element. The number of elements supplied must match the number of pax breaks setup within the option. Zeros are returned.
Ex1Rate
Ex2Rate
Ex3Rate
Ex4Rate
Ex5Rate
DecimalThese five extras elements appear within an ExtraRates element, which can in turn appear within the elements AdultExtras, ChildExtras and InfantExtras elements (which contain the per adult extra rates, per child extra rates and per infant extra rates). Note that a rate for extra N should only appear if extra N is defined for the option the rate is being added to. Optional.

2.15 GetRate

Retrieves details of rates for one or more Tourplan options. Inputs are User, Password and the fields listed below. Output data items are zero or more DateRange elements (the DateRange element is the accepted by the SetRate request).

Input data items

Data itemTypeDescription
OptionCodeString (17)The 17 character option code of the option whose rates are wanted. Option code patterns can be supplied. Multiple OptionCode values can be supplied.
Opt_IDIntegerInternal Tourplan option identifier. Multiple Opt_ID values can be supplied.
Price_CodeString (2)If specified, limits the rates returned to the specified price code. Optional.
Date_FromDateIf specified, means that rate periods that end before Date_From are not returned. Optional.
Date_ToDateIf specified, means that rate periods that start after Date_To are not returned. Optional.
PaxBreakChildRatesBooleanBy default, child and infant rates are returned as the single values ChildRate and InfantRate (each element is omitted if the rate is 0). If the option has pax break rates then the rates returned are for the first pax break. If PaxBreakChildRates is Y then for options with pax breaks child and infant rates are returned in ChildBreakRate and InfantBreakRate elements. If an option has N pax breaks then N rates are returned (including zero rates). Rates for options with no pax breaks are always returned as ChildRate and InfantRate, regardless of the value supplied for PaxBreakChildRates. Optional (defaults to N).

2.16 SetInventory

The SetInventory request creates or updates an inventory allocation in Tourplan.

SetInventory has no outputs.

Input data items

User, Password. The remaining fields are discussed in groups: general fields about the allocation, and the per day inventory information.

General data items
Data itemTypeDescription
SupplierCodeString (6)A valid Tourplan supplier code. Required.
AllocationNameString (15)Allocation name. If this allocation already exists for the specified supplier then this request updates that allocation; otherwise this request creates a new allocation. Required.
AllocationDescriptionString (60)Allocation description. Optional.
AllocationType
OptionCode
String (1)
String (17)
These fields specify which options this allocation applies to. If AllocationType is S the allocation applies to all of the supplier's options (and no option codes can be supplied). Otherwise AllocationType is O and there are one or more OptionCode values that specify which options this allocation applies to. Optional (if not supplied for a new allocation then AllocationType defaults to S).
Per day inventory information

Per day inventory information is provided for one or more split codes, and within each split code for one or more unit types. For each PerDayInventory element, if there is already a record in the database then it is updated; otherwise it is created. Records for days not specified in the input are not changed.

Data itemTypeDescription
Split_CodeString (15)A valid Tourplan allocation split code. Required.
Unit_TypeString (2)A valid Tourplan allocation unit code. Required.
DateDateThe date that this per-day inventory information applies to. Required.
Release_PeriodIntegerRelease period (in days). Required for new records.
Max_QtyInteger (0..)Total availability on the specified day. Required for new records.
Bkd_QtyIntegerThe number of units currently booked. The number of units currently available for booking is Max_Qty - Bkd_Qty. The SetInventory request cannot assign a value to Bkd_Qty; GetInventory returns the current value of Bkd_Qty.
ReleasedBooleanSpecifies whether this inventory record has been released in Tourplan. The SetInventory request cannot assign a value to Released; GetInventory returns the current value of Released.
Request_OKBooleanSpecifies whether a service can be put on request if there is not sufficient inventory available. Optional (defaults to true for new records).

2.17 GetInventory

Retrieves details of selected Tourplan allocations.

Output data items are one or more of the Allocation elements accepted by SetInventory. The allocations returned are those that meet the filter conditions specified by the input parameters.

Input data items

Inputs are User, Password plus the fields listed below.

Data itemTypeDescription
SupplierCodeString (6)Allocations for the specified suppliers are returned.
DateFrom
DateTo
DateRange of dates that per day inventory records are required for. Required.
OptionCode
Opt_ID
String (17)
Integer
Only allocations that are general to the supplier, or that include one or more of the specified options are returned. Optional (if not supplied then no filtering based on options is done).
AllocationNameString (15)Only allocations with this name are returned. Optional (if not supplied then no filtering on allocation name is done).
Split_CodeString (15)Only details for this split code are returned for each allocation. Optional (if not supplied then no filtering on split code is done).
Unit_TypeString (15)Only details for this unit type are returned for each allocation. Optional (if not supplied then no filtering on unit type is done).

 

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