11. 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.
11.1. 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.
11.1.1. Example input - Best Available¶
<availability_options>
<user_id>demo</user_id>
<crypto_block>k_--2mkKzCy6__eBiVuAEjWbPP-6j-t23qyus1WRvXvxPO_-r
K5taZhef6g-L_wPBFPfmOwEtdYhbqKOhQytgJjN1yNrlwZyf3B_zUF6_us7qlO7
fqqXIkx7L2PNHZukG9OJPgLi6jKdqzssmHP0XLu2L---Z</crypto_block>
<perf_token>s---AbiZwDdZo2IRYmd5syKAobBBYQzAWytxi6OfJrtADdu3G1w
2v0VRS73EPHDcefb4_PiwgmZrxa4-Y</perf_token>
<no_of_tickets>2</no_of_tickets>
</availability_options>
11.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.
11.2.1. Example output - Best Available¶
<availability_options_result>
<crypto_block>M0--JM6i0EQWP6-8XYFS5NtKtyH9n9jxN3okpA68pfOqZmu_3
V_aTkh0s2-VaPIeqyYmSrPflpYcGgIlN4ueM4rtMBAuHU0s-Chiqu58LuRCDGk6
aTfewQEJR0e3Jh3agWR8HxBKzW3bSO9mym-lqjodJdM32pH2JMBZboMXX2u16MA
GffiMjj1aOadFFBviIwBwLsdDuQYfvi6-Z</crypto_block>
<availability>
<ticket_type>
<ticket_type_desc>Dress Circle</ticket_type_desc>
<price_band>
<ticket_price>36.000</ticket_price>
<surcharge>0.000</surcharge>
<number_available>4</number_available>
<is_offer>yes</is_offer>
<non_offer_ticket_price>38.000</non_offer_ticket_price>
<non_offer_surcharge>4.000</non_offer_surcharge>
<band_token>U_--ATV757qGkCzGDsDy_gCsuOZBFFQp1Svzf0RE81wJA6-bic_
3MR4vDntfdzeQuD5Wpi85avRMwrPGz7Pt9qO9m5OgMThRVv6l6kYbnEvV9fqatN
WdO2ycuV6DqXqPLBFbY</band_token>
</price_band>
</ticket_type>
<ticket_type>
<ticket_type_desc>Front Stalls</ticket_type_desc>
<price_band>
<ticket_price>33.000</ticket_price>
<surcharge>0.000</surcharge>
<number_available>4</number_available>
<example_seats>
<id>FS304</id>
<id_details>
<row_id>FS</row_id>
<separator/>
<col_id>304</col_id>
</id_details>
<id>FS305</id>
<id_details>
<row_id>FS</row_id>
<separator/>
<col_id>305</col_id>
</id_details>
</example_seats>
<is_offer>no</is_offer>
<band_token>U_--KZ0dpI-zHbEkgg_2xk0RPEG6QYZ10iy85gv_KPpIUnAbic_
3MR4vDHobW9p4lyP_pi85avRMwrPGz7Pt9qO9mLXPVOSa5hJVCfjP4V-HgiASYU
uR93hITX6DqXqPLBFbY</band_token>
</price_band>
</ticket_type>
</availability>
<quantity_options>
<valid_quantity>1</valid_quantity>
<valid_quantity>2</valid_quantity>
<valid_quantity>3</valid_quantity>
<valid_quantity>4</valid_quantity>
<valid_quantity>5</valid_quantity>
<valid_quantity>6</valid_quantity>
<valid_quantity>7</valid_quantity>
<valid_quantity>8</valid_quantity>
<valid_quantity>9</valid_quantity>
</quantity_options>
<despatch_options>
<despatch_method>
<despatch_type>collect</despatch_type>
<despatch_desc>Collect</despatch_desc>
<despatch_cost>2.200</despatch_cost>
<despatch_token>-_--HSah6JpCk1lRW675lB2tGMmQ6IWjrA9Re8VC-wenb8W
rAVpWWLH0pmfFRAKPZnaomxlMt2aMjmZMD2e38gPzc_--Y</despatch_token>
</despatch_method>
<despatch_method>
<despatch_type>post</despatch_type>
<despatch_desc>Post (uk only)</despatch_desc>
<despatch_cost>2.200</despatch_cost>
<despatch_token>M_--b1G0pkpUhA74yv2l_B3uKkP_T0jnfS4-BGSuUxTPI4E
Bi9_RumDFvcKO6CuuYNGSwakOwgh99t4ikSliaoX5SbMBZDMmFBgxrlOqE6cs8e
z3SuXC5tui90--Y</despatch_token>
<permitted_countries>
<country>
<country_code>uk</country_code>
<country_desc>The United Kingdom</country_desc>
</country>
</permitted_countries>
</despatch_method>
<despatch_method>
<despatch_type>post</despatch_type>
<despatch_desc>Post</despatch_desc>
<despatch_cost>3.750</despatch_cost>
<despatch_token>-_--ATP0VErai-3xC7y4v5IgyhRdukn1IxoAZII1vDd8Hrb
lFe-RN4DE9GK1j1dMhTcyvdhAGRlUvgEdwMZ3Lz_UB0--Y</despatch_token>
</despatch_method>
</despatch_options>
<currency>
<currency_code>gbp</currency_code>
<currency_number>826</currency_number>
<currency_pre_symbol>£</currency_pre_symbol>
<currency_post_symbol/>
</currency>
</availability_options_result>
11.3. 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.
11.3.1. Example input - Seat Selection¶
<availability_options>
<no_of_tickets>10</no_of_tickets>
<perf_token>s---LnxImyj0QRe9KRc0d2rl3umfVtnnKdG_8QZeW5WLlxZZOqTeKbCrHRDt_Pdrnjjphc4mtPXPNxl7-Y</perf_token>
<add_free_seat_blocks/>
<user_id>ftbo</user_id>
<self_print_mode>html</self_print_mode>
<crypto_block>s_--_lqCiM_yZuBvBc9G8ChpLi5cLouN4dACnbfGEh3VX1pGbRlZ5KbU8_7bWXrZZZD9Knqt3ld_uw5tZbkDu2Zhj7JcqZX9ZOqOhm_GFtJc4-6r7oYgcjzuM38N_q0295S4a71Tfjq8A1CPvQX67joBHSZbywcIojoEZ</crypto_block>
</availability_options>
11.4. Output data - Seat Selection¶
11.4.1. Example output - Seat Selection¶
<availability_options_result>
<subdomain_user_is_bad>yes</subdomain_user_is_bad>
<quantity_options>
<valid_quantity>1</valid_quantity>
<valid_quantity>2</valid_quantity>
<valid_quantity>3</valid_quantity>
<valid_quantity>4</valid_quantity>
<valid_quantity>5</valid_quantity>
<valid_quantity>6</valid_quantity>
<valid_quantity>7</valid_quantity>
<valid_quantity>8</valid_quantity>
<valid_quantity>9</valid_quantity>
<valid_quantity>10</valid_quantity>
</quantity_options>
<crypto_block>60---Ny2iNMboaN4UGhpddRc5XZAAGgirdtSMLOLtGg1tqQ2D-7Jh2wNe3JCzdGsVrDTg4hn9zdpQMWDg9dkLcpRq6BTQBWoWYp6pS-2xkmTHVnViueT9L4q0CL5Wm3Uh-Uiq5WNty1oFl0ULZ-6bvUP2LKAVgdxA9_MtJv3OelcycsgVTpvzZydH0--Z</crypto_block>
<event>
<area_code>WE</area_code>
<area_desc>West End</area_desc>
<bigup_value>196</bigup_value>
<city_code>london-uk</city_code>
<city_desc>London</city_desc>
<class>
<class_code>theatre</class_code>
<class_desc>Theatre</class_desc>
<is_main_class>yes</is_main_class>
<search_key>theatre/</search_key>
<subclass>
<is_main_subclass>yes</is_main_subclass>
<search_key>theatre/kids</search_key>
<subclass_code>kids</subclass_code>
<subclass_desc>Family</subclass_desc>
</subclass>
<subclass>
<is_main_subclass>no</is_main_subclass>
<search_key>theatre/musicals</search_key>
<subclass_code>musicals</subclass_code>
<subclass_desc>Musicals</subclass_desc>
</subclass>
</class>
<country_code>uk</country_code>
<country_desc>United Kingdom</country_desc>
<critic_review_percent>80</critic_review_percent>
<date_range_end>
<date_desc>Sun, 2nd October 2016</date_desc>
<date_utc_offset>3600</date_utc_offset>
<date_utc_seconds>1475415000</date_utc_seconds>
<date_yyyymmdd>20161002</date_yyyymmdd>
</date_range_end>
<date_range_start>
<date_desc>Wed, 21st October 2015</date_desc>
<date_utc_offset>3600</date_utc_offset>
<date_utc_seconds>1445434200</date_utc_seconds>
<date_yyyymmdd>20151021</date_yyyymmdd>
</date_range_start>
<event_code>175</event_code>
<event_desc>The Lion King</event_desc>
<event_id>25DR</event_id>
<event_lingo>theatre</event_lingo>
<event_status>live</event_status>
<event_subdata/>
<geo_data>
<latitude>51.511784</latitude>
<longitude>-0.119622</longitude>
</geo_data>
<is_seated>yes</is_seated>
<need_departure_date>no</need_departure_date>
<need_duration>no</need_duration>
<need_performance>yes</need_performance>
<postcode>WC2E 7RQ</postcode>
<search_distance_km>0.0</search_distance_km>
<show_perf_time>yes</show_perf_time>
<source_code>atg_disney</source_code>
<source_desc>Ambassador Theatre Group</source_desc>
<venue_code>LYC/T</venue_code>
<venue_desc>The Lyceum</venue_desc>
</event>
<performance>
<date_desc>Sun, 1st November 2015</date_desc>
<date_utc_offset>0</date_utc_offset>
<date_utc_seconds>1446388200</date_utc_seconds>
<date_yyyymmdd>20151101</date_yyyymmdd>
<has_pool_seats>yes</has_pool_seats>
<is_limited>no</is_limited>
<perf_id>25DR-41W</perf_id>
<perf_is_visible>yes</perf_is_visible>
<perf_subdata>20036438</perf_subdata>
<perf_type_code>739796</perf_type_code>
<time_desc>2.30 PM</time_desc>
<time_hhmmss>143000</time_hhmmss>
</performance>
<currency>
<currency_code>gbp</currency_code>
<currency_factor>100</currency_factor>
<currency_number>826</currency_number>
<currency_places>2</currency_places>
<currency_post_symbol/>
<currency_pre_symbol>£</currency_pre_symbol>
</currency>
<availability>
<ticket_type>
<price_band>
<absolute_saving>5.83</absolute_saving>
<band_token>k6--Vsj7Zhye7ZK6vZB6q37K97YuElGkbQq6E0ezCaGJEJFhBi0hysJKNw8SurgRlBSmJHJ09AQwbyXztDKqojzdkSLSbcbzhSLU4OseiRHVTNtq4QskSBJkXgAi7GQOLUR4xPHBVBiuaJrCOE0I2oAPZ6njJBSqySXGG0XGlYRIrE2ckhNVAl3T5Hn3HKrGcbCSOllDF-GHZw-vecnJC208Tm5KSYZIkdQP86XE48Knc8trOxkBuEE7pfKiFytWPyzbB_0ZL0MJzy7q-G2DLS9wEZS16kbAckdJBUaX_ad-izNaWHWstY576oiOKU0Oi6rcHIbBGRolCxATqdR-2MXevROwRX_g2-strR6W_jTvtYwsYe9yfH42ytMTau5CV2uSfPn7JAyHtxgu-FdpcTgejIcUv-tbOjMdXYq9sOIvFh6FcIlvyT_qxbciVn1qKg1tIqckxsJmaoYPRqKetzh-eb0x5yA6Tm7JbUPOFuIQZDeSXW_RMbhoDLuFTclvSNIj5dC2mvrVoq5DGPW910MXjnvRbAlvaM7JK2SDYWDW0z770Xd9fP1b4YHxROejKmUgEOjrovx9llLflQhDkXgxjIlqGwFnFTWHy09IsU4e3xVm823LgPoOmU4yw8Eu33ZaHcvPjnFaYUy0LKJQug1j_PLFVxzSzYtN6q2N7dyqpxgnkpK72aeWd9PfYGP8l8L9KSpb3VYMkGWQ0P7BhwWEX2_HJDUFLIHnObGyEneL05_-Z</band_token>
<combined>65.32</combined>
<discount_code>TSA/IN8/1</discount_code>
<discount_desc>Special Offer</discount_desc>
<discount_subdata>TSA</discount_subdata>
<example_seats>
<id>E12</id>
<id>E11</id>
<id>E10</id>
<id>E9</id>
<id>E8</id>
<id>E7</id>
<id>E6</id>
<id>E5</id>
<id>E4</id>
<id>E3</id>
<id_details>
<col_id>12</col_id>
<full_id>E12</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/5</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>11</col_id>
<full_id>E11</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/6</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>10</col_id>
<full_id>E10</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/7</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>9</col_id>
<full_id>E9</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/8</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>8</col_id>
<full_id>E8</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/9</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>7</col_id>
<full_id>E7</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/10</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>6</col_id>
<full_id>E6</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/11</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>5</col_id>
<full_id>E5</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/12</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>4</col_id>
<full_id>E4</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/13</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>3</col_id>
<full_id>E3</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/14</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
</example_seats>
<example_seats_are_real>yes</example_seats_are_real>
<free_seat_blocks>
<seat_block>
<block_length>12</block_length>
<id_details>
<col_id>12</col_id>
<full_id>E12</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/5</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>11</col_id>
<full_id>E11</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/6</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>10</col_id>
<full_id>E10</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/7</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>9</col_id>
<full_id>E9</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/8</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>8</col_id>
<full_id>E8</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/9</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>7</col_id>
<full_id>E7</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/10</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>6</col_id>
<full_id>E6</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/11</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>5</col_id>
<full_id>E5</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/12</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>4</col_id>
<full_id>E4</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/13</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>3</col_id>
<full_id>E3</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/14</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>2</col_id>
<full_id>E2</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/15</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>1</col_id>
<full_id>E1</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>E</row_id>
<seat_subdata>159/16</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<seat_block_token>M0--SdCy7MKblc1On7krLWG8CYxMABgOLuP5zsdpzYmcgY1INc_CQRcjesNUmM_nXA2vfoUzm1hdfsAXpsPV8_GOamlJV_qAvDjVVLgRqh67w-CG4cuvWUs9EB2IgRj70JFLf_EORW9vBtTLTIg_JpQ2o6PpNeoUnknJbYTQLizCKsh_kl_BgR6sBESVS9QJw8NAzf1uRkyC-v4-Z</seat_block_token>
</seat_block>
</free_seat_blocks>
<is_offer>yes</is_offer>
<non_offer_combined>71.15</non_offer_combined>
<non_offer_seatprice>59.5</non_offer_seatprice>
<non_offer_surcharge>11.65</non_offer_surcharge>
<non_offer_ticket_price>59.5</non_offer_ticket_price>
<number_available>10</number_available>
<percentage_saving>8</percentage_saving>
<price_band_code>H</price_band_code>
<price_band_desc/>
<price_band_subdata/>
<raw_contiguous_seats>12</raw_contiguous_seats>
<raw_total_seats>50</raw_total_seats>
<seatprice>59.5</seatprice>
<surcharge>5.82</surcharge>
<ticket_price>59.5</ticket_price>
</price_band>
<ticket_type_code>GRA</ticket_type_code>
<ticket_type_desc>Grand Circle</ticket_type_desc>
<ticket_type_token>6_--KRY0ixwbqXwzr05kpH6MWUTX78zPoiFF1vvvn5bsirz5rvJKQgETdo0f-R830UL9BYIzpz24pyqP6e163hT3uw7HhDqQ64WhY</ticket_type_token>
</ticket_type>
<ticket_type>
<price_band>
<absolute_saving>7.13</absolute_saving>
<band_token>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</band_token>
<combined>79.62</combined>
<discount_code>TSA/IN8/1</discount_code>
<discount_desc>Special Offer</discount_desc>
<discount_subdata>TSA</discount_subdata>
<example_seats>
<id>H42</id>
<id>H41</id>
<id>H40</id>
<id>H39</id>
<id>H38</id>
<id>H37</id>
<id>H36</id>
<id>H35</id>
<id>H34</id>
<id>H33</id>
<id_details>
<col_id>42</col_id>
<full_id>H42</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/1</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>41</col_id>
<full_id>H41</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/2</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>40</col_id>
<full_id>H40</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/3</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>39</col_id>
<full_id>H39</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/4</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>38</col_id>
<full_id>H38</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/5</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>37</col_id>
<full_id>H37</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/6</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>36</col_id>
<full_id>H36</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/7</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>35</col_id>
<full_id>H35</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/8</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>34</col_id>
<full_id>H34</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/9</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>33</col_id>
<full_id>H33</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/10</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
</example_seats>
<example_seats_are_real>yes</example_seats_are_real>
<free_seat_blocks>
<seat_block>
<block_length>11</block_length>
<id_details>
<col_id>42</col_id>
<full_id>H42</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/1</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>41</col_id>
<full_id>H41</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/2</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>40</col_id>
<full_id>H40</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/3</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>39</col_id>
<full_id>H39</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/4</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>38</col_id>
<full_id>H38</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/5</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>37</col_id>
<full_id>H37</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/6</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>36</col_id>
<full_id>H36</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/7</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>35</col_id>
<full_id>H35</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/8</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>34</col_id>
<full_id>H34</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/9</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>33</col_id>
<full_id>H33</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/10</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<id_details>
<col_id>32</col_id>
<full_id>H32</full_id>
<is_restricted_view>no</is_restricted_view>
<row_id>H</row_id>
<seat_subdata>497/11</seat_subdata>
<seat_text_code/>
<separator/>
</id_details>
<seat_block_token>E0--J1UxyYpmJdq6dSQmvwgijFUWxKIhyPkJkNNiKKzbS4TzdWplZFXV-turLvp-082FmkGJkkEKyQIQQjXCeKDZVmLFGIWPneZrooecP07DRUG9XNIB_0888agzvv0U-6ygcpB-9lh4UTyt-rp5PW4XepfW-NRdNy_e78UXDhsiVh0S1qrwEEH0KtkhtgYN_VnrZ</seat_block_token>
</seat_block>
</free_seat_blocks>
<is_offer>yes</is_offer>
<non_offer_combined>86.75</non_offer_combined>
<non_offer_seatprice>72.5</non_offer_seatprice>
<non_offer_surcharge>14.25</non_offer_surcharge>
<non_offer_ticket_price>72.5</non_offer_ticket_price>
<number_available>10</number_available>
<percentage_saving>8</percentage_saving>
<price_band_code>A</price_band_code>
<price_band_desc/>
<price_band_subdata/>
<raw_contiguous_seats>11</raw_contiguous_seats>
<raw_total_seats>148</raw_total_seats>
<seatprice>72.5</seatprice>
<surcharge>7.12</surcharge>
<ticket_price>72.5</ticket_price>
</price_band>
<ticket_type_code>ROY</ticket_type_code>
<ticket_type_desc>Royal Circle</ticket_type_desc>
<ticket_type_token>6_--lI3a6YVP3iu2TajQFriIn21CmJMdk0G1pehc8u135KW0IsJPAGyZGLdYt5UzD7BuBYIzpz24pyqP6e163hT3uw7HhDqQ64WhY</ticket_type_token>
</ticket_type>
</availability>
<can_leave_singles>yes</can_leave_singles>
<despatch_options>
<despatch_method>
<despatch_code>C</despatch_code>
<despatch_cost>0.0</despatch_cost>
<despatch_desc>Collect at the venue</despatch_desc>
<despatch_subdata/>
<despatch_token>M_--ACN9t_zmkiemyjBEoCmxwOuQbd2zr1tR3vqGe9-nnQFC28i_t3JuWCQ7VGnjPX-qP32c2XV9Zai2hMlsligh3x5REZpcnzbLmbqpwXAgoA_CSwhrXppmO_--Y</despatch_token>
<despatch_type>collect</despatch_type>
</despatch_method>
</despatch_options>
</availability_options_result>
11.5. 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.
11.5.1. Example commission input¶
<availability_options>
<add_user_commission/>
<perf_token>k---0vlzY4A5OPEFLpadk9ez2C5dPIVtjhU1QKfZD3D6om4vAVT9em8CYx9QTFO3U5IzY</perf_token>
<self_print_mode>html</self_print_mode>
<user_id>whitelabel-testuser</user_id>
<crypto_block>k_--_lqCiM_yZuxPR5zF3-jt1i2RjkC2-bKcvFLNpfX27FJCF1XRT3x6KlQRfG-BHZvMwlt12LJ0xG_W86-WADZ6R5-pK_1OjQZNX7rQx6-_hl0hCtxCDKRImnTdxihARp3gCbCY0xeFsOhT1F19g1hAR0--Z</crypto_block>
</availability_options>
11.5.2. Example commission output stub¶
The response will include the following user_commission element:
<user_commission>
<amount_excluding_vat>0.0</amount_excluding_vat>
<amount_including_vat>0.0</amount_including_vat>
<commission_currency>
<currency_code>gbp</currency_code>
<currency_factor>100</currency_factor>
<currency_number>826</currency_number>
<currency_places>2</currency_places><currency_post_symbol/>
<currency_pre_symbol>£</currency_pre_symbol>
</commission_currency>
<currency>gbp</currency>
</user_commission>
11.6. 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.