The *availability\_options* method
==================================
With an event and its associated date and time information this method
calculates the currently available tickets and returns a list of the
types of tickets which may be purchased, along with any restrictions on
the number of tickets. Availability is divided into a set of ticket
types, and within each ticket type a subdivision into pricing bands. A
pricing band will contain the price of a single ticket, plus the value
of any per-ticket surcharge which will be added to the booking. The
maximum number of tickets that are allowed to be booked for that
particular price band is also indicated. Potentially the method may also
return a set of example seats, indicating the kind of seats which may be
available for that price band. Note that these are examples only and are
not intended as an indication of the actual seats which will be sold.
It is possible for the method to return actual seats, however, but
this must be requested explicitly, and the backend system must support
it.
Some events are restricted to certain combinations of tickets, the most
common being tickets which may only be purchased in pairs. A list is
returned containing the set of valid possibilities for the number of
tickets that may be purchased. Only values from the list will be
accepted for bookings. A list of possible methods of despatching the
tickets to the customer is also provided. Depending on the particular
product, a ticket may be held for collection, or posted to the customer
(subject to a number of restrictions on timing and postal areas). Each
method in the list has an associated cost which will be added to the
overall ticket charge.
It should be noted that the availability provided by the system is in
real time and represents what was available at the time the request was
made. There is thus no guarantee that the tickets will still be
available to purchase at some future time. Tickets are only guaranteed
to be held for a customer following a successful "reserve\_order"
method.
If you receive empty availability this can have at least the following meanings:
* There is no availability for this performance for the tickets you are permissioned to sell
* There was a problem communicating with the backend system. In this case the element backend\_call\_failed will be present.
* The request was rejected because it exceeded the limit availabile in our queue used to throttle the number of calls passed on to the backend systems. In this case the element backend\_call\_throttling\_failed will be present.
Required inputs - Best Available
--------------------------------
The basic required input is the "crypto\_block" produced at the output
of the "date\_time\_options" method. This holds the details of the event
required. If the event requires a departure date then this should be
specified in a "departure\_date" element in YYYYMMDD form. Similarly, if
the event requires a usage date then this should be provided in a
"usage\_date" element, also in YYYYMMDD form. For events which require a
performance to be selected from a list then the appropriate token should
be provided in a "perf\_token" element. If the number of
tickets that the customer requires is already known then this
can pe passed in using the "no\_of\_tickets" element. The inputs should have
been validated before being presented to the method as they will be checked
by the method and failure codes reported as appropriate if any problems
are found. This method has more potential failure codes than any other
in the system.
If the client software is capable of handling "self print vouchers" then
this must be indicated to the code via the "self\_print\_mode" input.
Setting this to "html" asks the core to include despatch methods
requiring the customer to print out a page of HTML representing their
tickets. Setting it to "custom" asks the core to include methods where
the client software can generate its own voucher as agreed in advance
with the venue. It is possible that no extra despatch methods will be
returned by using this element: the product may not support it, or in
the case of "custom" there may be no arrangement for the caller to
generate customer self print vouchers. If the client software picks a
selfprint despatch option, the same value of "self\_print\_mode" must be
passed to subsequent calls.
For clients which wish to display the exact seats, if available,
which will be offered, and to thus give the customer the opportunity
to select their own then the addition of an "add\_free\_seat\_blocks"
element will cause the list to be produced if available. For this to
work properly the number of seats required should be input
as the "no\_of\_tickets" element as described above.
If a set of orders is being accumulated in a trolley then the current
set may be passed in as "trolley\_token". If this is done then the list
of options returned by the method will be restricted to remove any which
are known to be incompatible with the current set of orders in the
trolley.
Example input - Best Available
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: xml
demo
k_--2mkKzCy6__eBiVuAEjWbPP-6j-t23qyus1WRvXvxPO_-r
K5taZhef6g-L_wPBFPfmOwEtdYhbqKOhQytgJjN1yNrlwZyf3B_zUF6_us7qlO7
fqqXIkx7L2PNHZukG9OJPgLi6jKdqzssmHP0XLu2L---Z
s---AbiZwDdZo2IRYmd5syKAobBBYQzAWytxi6OfJrtADdu3G1w
2v0VRS73EPHDcefb4_PiwgmZrxa4-Y
2
Output data - Best Available
----------------------------
The output data from the method divides into four sections. These are
the event availability, the list of valid ticket quantities, the list of
available despatch methods and the currency in use.
The ticket availability is found within the "availability" element. This
contains zero or more "ticket\_type" elements, each representing a
single type of ticket for which availability has been found. If there is
no availability for the ticket then the element will be empty, and none
of the subsequent elements will be present. Within each "ticket\_type"
element the description of the ticket type is to be found in the
"ticket\_type\_desc" element. The actual availability is contained
within one or more "price\_band" elements. Each of these represents a
particular pricing option for tickets of that type. A "price\_band"
element contains the main price as a three decimal place value in the
"ticket\_price" element, plus any per ticket surcharge which may be
applied in the "surcharge" elements. The number of tickets actually
available to be booked is present in the "number\_available" element for
each price band, and a token to identify the band for the purposes of
creating an order is provided as "band\_token". If the price being
returned is known to be a spceial offer, where the ticket is normally
available at a higher cost, then the element "is\_offer" will contain
"yes", and will then be followed by two elements called
"non\_offer\_ticket\_price" and "non\_offer\_surcharge" which will
contain the usual price. Under normal circumstances the "is\_offer"
elementing will contain "no", however, and these two extra elements will
be absent. If example seat data is available then this will be provided
in an element called "example\_seats". The format of each seat is the
same as in a standard trolley and can be found in the documentation for
the the "trolley\_describe" method.
If the free seat blocks have been requested then these also be available
in an element called "free\_seat\_blocks" after the example seats. This
element contains sets of seast in blocks, each within a "seat\_block"
element. A block contains an element "block\_length" containing
the count of seats within the block, and a "seat\_block\_token"
which will be used to specify the seat block selected. It then cotains
a set of "id\_details" elements, in order, representing the free seats.
Note that a block represents seats which may be seated together - hence
there is no requirement that a seat is only in one block and that
blocks do not overlap. The coder of a client should be aware of this.
Some tickets are restricted such that only specific quantities may be
purchased. This is most commonly used to restrict purchases to even
numbers of tickets only, or a single ticket at a time. The allowable
quantities are listed in the "quantity\_options" element, which contains
a list of "valid\_quantity" elements, each containing a single integer.
The quantity must be chosen from this list. As it is useful to know
this set of restrictions to select the number of seats before making
the availability call then it is possible to restrict the output to
just this list by adding a "quantity\_options\_only" element
at the input. Such a call will be very fast as it does not
make an actual availability request to the backend.
The options for despatching the tickets which may be selected are listed
within the "despatch\_options" element. If no options are available then
this element will be empty and the tickets cannot be purchased. Each
available despatch method is described within a "despatch\_method"
element. The type of the method is held in "despatch\_type", a text
description of the method in "despatch\_desc", the cost of the method in
"despatch\_cost" and finally a token to specify the actual method in
"despatch\_token".
The methods come in four basic types. The most generic is the "dynamic"
type. This type is provided when the user cannot select how the tickets
will be sent to them. The normal method would be to have the tickets
posted, but if this is not possible then they will be held for
collection. The choice between these two is determined at purchase time
and the buyer informed at this point. Until then the method is not
known. A despatch method of "collect" indicates that the tickets should
be collected by the customer and will not be posted. Under normal
circumstances the collection point is the box office at the venue. The
despatch type of "post" indicates that the tickets will be posted to the
customer's address. There may be several different post methods giving
various levels of postal service as options.
The final despatch type is "selfprint". This indicates that the customer
can print out their own ticket and take it to the venue for admission.
This despatch type will not be available unless it is specifically
requested via the "self\_print\_mode" input. Despatch methods of type
"selfprint" are usually supported by TicketSwitch generating an HTML
page representing the voucher. The client software must allow the
customer to print this HTML. Alternatively special arrangements can be
made between the client and individual venues to accept client-generated
vouchers. Which of these two cases is permitted can be determined by the
two elements "has\_html\_page" and "can\_generate\_self\_print", which
will be "yes" or "no". Both may be "yes" to allow both types of
selfprint voucher, but both will never be "no" at once.
Both the "post" and "dynamic" despatch methods may result in tickets
being posted, and some systems restrict the areas within which they
allow tickets to be sent. Under such circumstances a list of countries
will be provided and the customer must have an address located within
one of those countries in order to be able to select the method. The
list is provided in a "permitted\_countries" element, with each country
within a "country" element. The country's name is provided as
"country\_desc" along with a letter code as "country\_code". The code
"UK" is used in preference to "GB", all other codes are as per ISO 3166.
If the preceeding three lists are not empty then a final element
"currency" will be present indicating the currency of all listed prices.
This element contains the ISO 4217 three letter code and numeric
identifier as "currency\_code" and "currency\_number". For display
purposes the currencies symbol is also present. As some currencies
display the symbol before the numeric value, whilst others display it
after the value, then two elements are provided to cope with this. These
are "currency\_pre\_symbol" and "currency\_post\_symbol". The values
should be displayed between these two strings, one of which will
normally be of zero length.
As with the date and time options there may be extra pieces of text
which should be displayed to the customer when collecting the ticket
type, number of seats or despatch method. The three elements used to
hold this text are "collect\_type\_text", "collect\_seats\_text" and
"collect\_send\_text", with the final one corresponding to the despatch
method, as it is usually related to how the tickets will be sent. Within
these elements will be one or more "collect\_text" elements holding the
actual text to be displayed, and as with the date and time options there
may be more than one piece of text associated with each piece of
information. A fourth piece of text "collect\_confirmation\_text" may be
present if there is information that the customer should be made aware
of before confirming that they want to purchase the tickets.
Example output - Best Available
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: xml
M0--JM6i0EQWP6-8XYFS5NtKtyH9n9jxN3okpA68pfOqZmu_3
V_aTkh0s2-VaPIeqyYmSrPflpYcGgIlN4ueM4rtMBAuHU0s-Chiqu58LuRCDGk6
aTfewQEJR0e3Jh3agWR8HxBKzW3bSO9mym-lqjodJdM32pH2JMBZboMXX2u16MA
GffiMjj1aOadFFBviIwBwLsdDuQYfvi6-Z
Dress Circle
36.000
0.000
4
yes
38.000
4.000
U_--ATV757qGkCzGDsDy_gCsuOZBFFQp1Svzf0RE81wJA6-bic_
3MR4vDntfdzeQuD5Wpi85avRMwrPGz7Pt9qO9m5OgMThRVv6l6kYbnEvV9fqatN
WdO2ycuV6DqXqPLBFbY
Front Stalls
33.000
0.000
4
FS304
FS
304
FS305
FS
305
no
U_--KZ0dpI-zHbEkgg_2xk0RPEG6QYZ10iy85gv_KPpIUnAbic_
3MR4vDHobW9p4lyP_pi85avRMwrPGz7Pt9qO9mLXPVOSa5hJVCfjP4V-HgiASYU
uR93hITX6DqXqPLBFbY
1
2
3
4
5
6
7
8
9
collect
Collect
2.200
-_--HSah6JpCk1lRW675lB2tGMmQ6IWjrA9Re8VC-wenb8W
rAVpWWLH0pmfFRAKPZnaomxlMt2aMjmZMD2e38gPzc_--Y
post
Post (uk only)
2.200
M_--b1G0pkpUhA74yv2l_B3uKkP_T0jnfS4-BGSuUxTPI4E
Bi9_RumDFvcKO6CuuYNGSwakOwgh99t4ikSliaoX5SbMBZDMmFBgxrlOqE6cs8e
z3SuXC5tui90--Y
uk
The United Kingdom
post
Post
3.750
-_--ATP0VErai-3xC7y4v5IgyhRdukn1IxoAZII1vDd8Hrb
lFe-RN4DE9GK1j1dMhTcyvdhAGRlUvgEdwMZ3Lz_UB0--Y
gbp
826
£
Required inputs - Seat Selection
--------------------------------
If you want to get actual seat blocks back from availability_options you need to request them explicitly. This is done by adding an empty element "add_free_seat_blocks" to the call.
Note that not all events sold have individual seats available, so this option will not always return data.
If this is supplied then the call will contain an element 'free_seat_blocks' along with each price band. This holds the free seats for that price band.
Each free_seat_block element contains one or more 'seat_block' elements. Each of these represents a block of seats which can be selected from.
A seat block has the following elements:
- block_length - the number of seats in the block.
- seat_block_token - a token to identify the block in the API.
- multiple 'id_details' elements.
the id_details elements take the normal form for a seat_id within the XML core API and can be parsed by the same code.
Note that the seats within seat blocks are unique, but a seat may occur within more than one seat block - the blocks represent sets which can be selected from, and these may overlap. Also the order of the id_details elements is important within a block, as the selection will be contiguous within a block.
If you wish to select a block of seats then the selection is passed in at the discount_options stage. The only thing which is required is the 'seat_block_token' - if this is passed in then the first set of seats in that block will be selected. If you wish to select seats in the middle of a block (as would be normal) then a seat_block_offset is also passed in. This is an integer giving the position within the block. A zero means the start of the block, so it is effectively the number of seats skipped at the start.
Example input - Seat Selection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: xml
10
s---LnxImyj0QRe9KRc0d2rl3umfVtnnKdG_8QZeW5WLlxZZOqTeKbCrHRDt_Pdrnjjphc4mtPXPNxl7-Y
ftbo
html
s_--_lqCiM_yZuBvBc9G8ChpLi5cLouN4dACnbfGEh3VX1pGbRlZ5KbU8_7bWXrZZZD9Knqt3ld_uw5tZbkDu2Zhj7JcqZX9ZOqOhm_GFtJc4-6r7oYgcjzuM38N_q0295S4a71Tfjq8A1CPvQX67joBHSZbywcIojoEZ
Output data - Seat Selection
----------------------------
Example output - Seat Selection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: xml
yes
1
2
3
4
5
6
7
8
9
10
60---Ny2iNMboaN4UGhpddRc5XZAAGgirdtSMLOLtGg1tqQ2D-7Jh2wNe3JCzdGsVrDTg4hn9zdpQMWDg9dkLcpRq6BTQBWoWYp6pS-2xkmTHVnViueT9L4q0CL5Wm3Uh-Uiq5WNty1oFl0ULZ-6bvUP2LKAVgdxA9_MtJv3OelcycsgVTpvzZydH0--Z
WE
West End
196
london-uk
London
theatre
Theatre
yes
theatre/
yes
theatre/kids
kids
Family
no
theatre/musicals
musicals
Musicals
uk
United Kingdom
80
Sun, 2nd October 2016
3600
1475415000
20161002
Wed, 21st October 2015
3600
1445434200
20151021
175
The Lion King
25DR
theatre
live
51.511784
-0.119622
yes
no
no
yes
WC2E 7RQ
0.0
yes
atg_disney
Ambassador Theatre Group
LYC/T
The Lyceum
Sun, 1st November 2015
0
1446388200
20151101
yes
no
25DR-41W
yes
20036438
739796
2.30 PM
143000
gbp
100
826
2
£
5.83
k6--Vsj7Zhye7ZK6vZB6q37K97YuElGkbQq6E0ezCaGJEJFhBi0hysJKNw8SurgRlBSmJHJ09AQwbyXztDKqojzdkSLSbcbzhSLU4OseiRHVTNtq4QskSBJkXgAi7GQOLUR4xPHBVBiuaJrCOE0I2oAPZ6njJBSqySXGG0XGlYRIrE2ckhNVAl3T5Hn3HKrGcbCSOllDF-GHZw-vecnJC208Tm5KSYZIkdQP86XE48Knc8trOxkBuEE7pfKiFytWPyzbB_0ZL0MJzy7q-G2DLS9wEZS16kbAckdJBUaX_ad-izNaWHWstY576oiOKU0Oi6rcHIbBGRolCxATqdR-2MXevROwRX_g2-strR6W_jTvtYwsYe9yfH42ytMTau5CV2uSfPn7JAyHtxgu-FdpcTgejIcUv-tbOjMdXYq9sOIvFh6FcIlvyT_qxbciVn1qKg1tIqckxsJmaoYPRqKetzh-eb0x5yA6Tm7JbUPOFuIQZDeSXW_RMbhoDLuFTclvSNIj5dC2mvrVoq5DGPW910MXjnvRbAlvaM7JK2SDYWDW0z770Xd9fP1b4YHxROejKmUgEOjrovx9llLflQhDkXgxjIlqGwFnFTWHy09IsU4e3xVm823LgPoOmU4yw8Eu33ZaHcvPjnFaYUy0LKJQug1j_PLFVxzSzYtN6q2N7dyqpxgnkpK72aeWd9PfYGP8l8L9KSpb3VYMkGWQ0P7BhwWEX2_HJDUFLIHnObGyEneL05_-Z
65.32
TSA/IN8/1
Special Offer
TSA
E12
E11
E10
E9
E8
E7
E6
E5
E4
E3
12
E12
no
E
159/5
11
E11
no
E
159/6
10
E10
no
E
159/7
9
E9
no
E
159/8
8
E8
no
E
159/9
7
E7
no
E
159/10
6
E6
no
E
159/11
5
E5
no
E
159/12
4
E4
no
E
159/13
3
E3
no
E
159/14
yes
12
12
E12
no
E
159/5
11
E11
no
E
159/6
10
E10
no
E
159/7
9
E9
no
E
159/8
8
E8
no
E
159/9
7
E7
no
E
159/10
6
E6
no
E
159/11
5
E5
no
E
159/12
4
E4
no
E
159/13
3
E3
no
E
159/14
2
E2
no
E
159/15
1
E1
no
E
159/16
M0--SdCy7MKblc1On7krLWG8CYxMABgOLuP5zsdpzYmcgY1INc_CQRcjesNUmM_nXA2vfoUzm1hdfsAXpsPV8_GOamlJV_qAvDjVVLgRqh67w-CG4cuvWUs9EB2IgRj70JFLf_EORW9vBtTLTIg_JpQ2o6PpNeoUnknJbYTQLizCKsh_kl_BgR6sBESVS9QJw8NAzf1uRkyC-v4-Z
yes
71.15
59.5
11.65
59.5
10
8
H
12
50
59.5
5.82
59.5
GRA
Grand Circle
6_--KRY0ixwbqXwzr05kpH6MWUTX78zPoiFF1vvvn5bsirz5rvJKQgETdo0f-R830UL9BYIzpz24pyqP6e163hT3uw7HhDqQ64WhY
7.13
s6--b9mzaCVHKIOAjQyFWHADmg0TRbOAQoBEYjZBQgB4k2-5_Henreg7req-Ol65TaO5O8o1HFW1wIMiBHlJxYf_BgzLkKTlejbZrsTyhDkVVkt0qDRo9raB8LaUFTAa9xj19pEXUxlLOJGcuvrcJGk230k1erxTZmcBx76Us26VPtqZkz0Y5iAIQuU0bjgWSl-pDnYQNVGuEbs4B5xHVquIB8SRnE3WBsPx4eYeU49z_DsixXbcSSk_JCTYxtQc5qyNgpCSc54JhxDaRR3-ng3IG0A2nY3qaqTIi1_oG7FFoRcgfgEnEUR3eRV4QncQtpODF5QDAXwLXxG_h_FFGpq0Qm8I11Feb21NpG2eeurvVbaMKd1sz-TAlrAn0ELGynfcQOBoTiyR0l6cdGgw2qFzWzNnLHV_A6CQ1F_Iqf2h1IxhD9-_z8gAn-fzFCRflsheBzn4NRcm0EUOaelDoIN-Qx4n7CGg2w-agGOjqZvqU7jdjU5aJi0FEg0kIDnLZeQM72l7Z3fFuvOTOjFewuVj7bp2gZKcJU_kP32iXtcwSYx2NCb8PNw_Lt3_Zw7AXmPy2Z5U50rUxvmwX1YNIvMP7L-FaHt8T1mjJuSvfFY54b2eAkw0ZeKkEzTbl3Jyvx2YqHq7Jzf6K-JGomXdItgSXC5xirz4OnfWTbAGLACHRwKZo32ReRszUifOhixvORgPV39-KDG7B0IO121R-rzxqNxuK2fJzCDj3bOXndWpk2wAH5SRFXkWq1--Z
79.62
TSA/IN8/1
Special Offer
TSA
H42
H41
H40
H39
H38
H37
H36
H35
H34
H33
42
H42
no
H
497/1
41
H41
no
H
497/2
40
H40
no
H
497/3
39
H39
no
H
497/4
38
H38
no
H
497/5
37
H37
no
H
497/6
36
H36
no
H
497/7
35
H35
no
H
497/8
34
H34
no
H
497/9
33
H33
no
H
497/10
yes
11
42
H42
no
H
497/1
41
H41
no
H
497/2
40
H40
no
H
497/3
39
H39
no
H
497/4
38
H38
no
H
497/5
37
H37
no
H
497/6
36
H36
no
H
497/7
35
H35
no
H
497/8
34
H34
no
H
497/9
33
H33
no
H
497/10
32
H32
no
H
497/11
E0--J1UxyYpmJdq6dSQmvwgijFUWxKIhyPkJkNNiKKzbS4TzdWplZFXV-turLvp-082FmkGJkkEKyQIQQjXCeKDZVmLFGIWPneZrooecP07DRUG9XNIB_0888agzvv0U-6ygcpB-9lh4UTyt-rp5PW4XepfW-NRdNy_e78UXDhsiVh0S1qrwEEH0KtkhtgYN_VnrZ
yes
86.75
72.5
14.25
72.5
10
8
A
11
148
72.5
7.12
72.5
ROY
Royal Circle
6_--lI3a6YVP3iu2TajQFriIn21CmJMdk0G1pehc8u135KW0IsJPAGyZGLdYt5UzD7BuBYIzpz24pyqP6e163hT3uw7HhDqQ64WhY
yes
C
0.0
Collect at the venue
M_--ACN9t_zmkiemyjBEoCmxwOuQbd2zr1tR3vqGe9-nnQFC28i_t3JuWCQ7VGnjPX-qP32c2XV9Zai2hMlsligh3x5REZpcnzbLmbqpwXAgoA_CSwhrXppmO_--Y
collect
Net prices / commission
--------------------------------
By default only retail prices are returned by the API, but it is also possible to request commission. With this you can determine the net price or cost of each ticket to you.
net price = total retail price less commission paid to the affiliate; ie net price = combined - user_commission.
In order to request commission from availability you should add "add\_user\_commission/>" to your availability call.
Example commission input
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: xml
k---0vlzY4A5OPEFLpadk9ez2C5dPIVtjhU1QKfZD3D6om4vAVT9em8CYx9QTFO3U5IzY
html
whitelabel-testuser
k_--_lqCiM_yZuxPR5zF3-jt1i2RjkC2-bKcvFLNpfX27FJCF1XRT3x6KlQRfG-BHZvMwlt12LJ0xG_W86-WADZ6R5-pK_1OjQZNX7rQx6-_hl0hCtxCDKRImnTdxihARp3gCbCY0xeFsOhT1F19g1hAR0--Z
Example commission output stub
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The response will include the following user_commission element:
.. code-block:: xml
0.0
0.0
gbp
100
826
2
£
gbp
Potential failure codes
-----------------------
- **1** - the supplied crypto block was not generated by
"date\_time\_options"
- **2** - the requested "mime\_text\_type" was not a supported value
- **301** - no "departure\_date" has been supplied when required
- **302** - a "departure\_date" has been supplied when not required
- **303** - no "usage\_date" has been supplied when required
- **304** - a "usage\_date" has been supplied when not required
- **305** - no "perf\_token" has been supplied when required
- **306** - a "perf\_token" has been supplied when not required
- **307** - the "departure\_date" element was badly formatted
- **308** - the "usage\_date" element was badly formatted
- **309** - the specified departure date is in the past
- **310** - the specified usage date is in the past
- **311** - the specified usage date is before the departure date
- **312** - the specified usage date is not allowed
- **313** - the supplied "perf\_token" is corrupt
- **314** - the specified departure date is after the performance
- **315** - the supplied "trolley\_token" is corrupt
There are two failure conditions where you will see empty availability but no error message:
- if backend\_call\_failed is present then there was a problem communicating with the backend system
- if backend\_call\_throttling\_failed is present then the request was rejected because it exceeded the limit availabile in our queue used to throttle the number of calls passed on to the backend systems.