12. The discount_options method

The tickets prices returned by the “availability_options” method standard tickets at whatever the default price is. In many cases there are discounts which may be applied to an order such as children’s tickets, or student discounts for example. This method takes the specification for a set of available tickets, and lists the discounts which may be applied to the tickets, including the standard price. For some products a single discount may be applied across the whole order only, whereas for others each ticket within the order may have an individual discount applied to it, though there may be a limit to the number of different combinations allowable in total.

Certain backend systems do not support discount codes, and products may only be sold at the face value given in the “availability_options” method. In this case there will be no data returned from this method other than the “crypto_block”, and this should be passed directly to “create_order”. This is very different from the method returning an empty list of discounts, which indicates that there are no valid discounts available for the selected product, and it cannot be purchased.

12.1. Required inputs

The “crypto_block” from the preceeding availability method is required, along with a “band_token” specifying the desired price band, a “despatch_token” specifying the desired despatch method, and also an integer as “no_of_tickets”. The number of tickets must be one of the values from the “quantity_options” list and must not be greater than the number of available tickets in the specified price band. For clients which are selecting spfici seats then the “seat_block_token” of the selection must be present, along with a “seat_block_offset” containing the offset into the block. Zero is the start of the block, and if this element is absent then the offset will be assumed to be zero. If a trolley is in use then this should be passed in as “trolley_token”, as this may affect the outcome of the method.

12.1.1. Example input

<discount_options>
<user_id>demo</user_id>
<crypto_block>M0--oX9hZ06WidmBy_GzZH_v3BTAN5QiFzArykxocsSIk2tu4
ZlLKIZOPBHgL5I2diqffFKYNgSrkOL8PuRAX-gL0stZ7Bv1O-zLZ_Z8FJnLEK-Z
_dqqCESP3hsmf7GyBcH6EVsX4PhjhdppKWlkFV_r71QjGnUIqzlCg2QZRsvQrd1
ujFk0y8xRxk5LyTq4Q-3FLsdDuQYfvi6-Z</crypto_block>
<band_token>U_--KZ0dpI-zHbEkgg_2xk0RPEG6QYZ10iy85gv_KPpIUnAbic_
3MR4vDHobW9p4lyP_pi85avRMwrPGz7Pt9qO9mLXPVOSa5hJVCfjP4V-HgiASYU
uR93hITX6DqXqPLBFbY</band_token>
<no_of_tickets>2</no_of_tickets>
<despatch_token>M_--b1G0pkpUhA74yv2l_B3uKkP_T0jnfS4-BGSuUxTPI4E
Bi9_RumDFvcKO6CuuYNGSwakOwgh99t4ikSliaoX5SbMBZDMmFBgxrlOqE6cs8e
z3SuXC5tui90--Y</despatch_token>
</discount_options>

12.2. Output data

The output data always includes a “crypto_block” to be passed to the “create_order” method. If the order is for a product which cannot be discounted, then no other information will be present in the output. For orders which may be discounted, however, there will always be a “blanket_discount_only” element and one or more “discounts” elements following the “crypto_block”.

The “blanket_discount_only” element contains a boolean value of “yes” or “no”. This indicates whether or not discounts may be selected for each individual ticket within the order, or whether a single blanket discount must be applied across the order as a whole. Blanket discounts are unusual, but may occur in such situations as a product which may be purchased at a normal rate, or a special offer rate, but not a mixture of the two. More common is for a limit to be placed on the number of different types of discount which may be applied to an order. If this is the case then an element “discount_limit” will be present, containing an integer indicating the number of different discount types that may be mixed in the order. In order to distinguish discount types there is a “discount_type” element associated with each discount. Discounts with the same “discount_type” are considered to be the same even though they will have different tokens.

For blank discounts there will only be one “discounts” element, else there will be a “discounts” element for each of the seats in the order. One discount should be chosen from each of the lists, taking care not to exceed any limit set by the “discount_limit” element.

A “discounts” element contains a list of “discount” elements. If a list is empty it indicates that there are no valid discounts for the order, and thus the order cannot be purchased. This may happen despite the apparent presence of ticket availability at the previous stage. The system does not guarantee the availability of any product until a reservation has been made. Each “discount” element in the list contains “ticket_price” and “surcharge” elements for that particular discount. These have the same meaning as in the “price_band” returns from the “availability_options” method. A token is provided to identify the discount in a “discount_token” element. Each discount normally has a “discount_desc” element containing the human readable description of the discount. The only discount which does not contain this is the one corresponding to the standard price for the product. There is not necessarily a standard discount available in the list, but if so then it will be indicated by the lack of a description. Each “discounts” list will contain different tokens for the elements of the list so in order to be able to tell how many different types of discount have been selected a “discount_type” element is present for each, which indicates which tokens refer to the same type of discount.

As with all other pieces of information there may be extra text to be displayed when prompting for a discount code. If any such text exists it will be found in the optional “collect_discounts_text” element, with each piece of text being within a “collect_text” element. This is the same as for the extra text associated with the date/time options and the availability options.

12.2.1. Example output

<discount_options_result>
<crypto_block>U1--Nq2HPJSjr9CrdElqdlMo4566Y3uXgV5uorhh0OTj7Uema
MCdc_OdGkbgD7w8NVmr80hEB45iIGeO3wfRwnlU-9_kWJcvIXy3Q0oPq5qwP-85
WNAEBo4CfCn0u6dS8czfD1H-Oy0tLFeVCb6Aqgn41_5pJry1jlp8oGgcKXVtPtp
owaoG6ieefxBL12spf1RDgjtpjcqfykcYVZgeQrSiMiENVrdsHOVLDmh9TPSJyq
7qk2KQwEvabAOrs-vW9otaXdPAJMvE8MCUS60TYJ-hDInDdo5roes5i4UpGGzuq
yA-Z</crypto_block>
<blanket_discount_only>no</blanket_discount_only>
<discount_limit>3</discount_limit>

<discounts>
<discount>
<discount_desc>First Call Standard Sale</discount_desc>
<ticket_price>33.000</ticket_price>
<surcharge>0.000</surcharge>
<discount_token>M_--IbGqi00j3ybOpqyoBkzpk7VaFCjbF7_8CJX4e5KsEPl
3SM94d2GAQWwBs4LIQjijy4IGDFmAaL4aDA1A1CgvbaOdb5kQwqgIYZYts850V7
xYDjouGoFr30--Y</discount_token>
<discount_type>0</discount_type>
</discount>

<discount>
<discount_desc>Westminster Residents Card.</discount_desc>
<ticket_price>16.500</ticket_price>
<surcharge>0.000</surcharge>
<discount_token>M_--8hntACS_vMmM5of6SXwEpKIf9dhTztSubkHOtXwxPkd
SlBHV599lVT4h_wD5hIJDdbMszQlwT1-7ga9Lbp4NOMdKUf_Pgwja5W1ObZwQfk
7_GOEFywVtp---Y</discount_token>
<discount_type>1</discount_type>
</discount>
</discounts>

<discounts>
<discount>
<discount_desc>First Call Standard Sale</discount_desc>
<ticket_price>33.000</ticket_price>
<surcharge>0.000</surcharge>
<discount_token>Q_--8gf6jbc0j3ybOpqyoBkzpk7VaFCjb7_8CJX4e5KsEPl
3sM94d2GAQWwBs4LIQjijy4IGDemAaL4aDA1A1CgvbaOdb5kQwqgIYZYts850V7
xYDjouGoFr30--Y</discount_token>
<discount_type>0</discount_type>
</discount>

<discount>
<discount_desc>Westminster Residents Card.</discount_desc>
<ticket_price>16.500</ticket_price>
<surcharge>0.000</surcharge>
<discount_token>F_hgt8ntACS_vMmM5of6SXwEpKIf9dhTztSubkHOtXwxPkd
SlBHV599lVT4h_wD5hIJDdbMszQlwT1-7ga9Lbp4NOMdKUf_Pgwja5W1ObZwQfk
7_GOEFywVtp---Y</discount_token>
<discount_type>1</discount_type>
</discount>
</discounts>

</discount_options_result>

12.3. Potential failure codes

  • 1 - the supplied crypto block was not generated by
    “availability_options”
  • 2 - the requested “mime_text_type” was not a supported value
  • 401 - no “band_token” has been supplied
  • 402 - the supplied “band_token” is corrupt
  • 403 - no “despatch_token” has been supplied
  • 404 - the supplied “despatch_token” is corrupt
  • 405 - no “no_of_tickets” element has been supplied
  • 406 - the “no_of_tickets” element is not an integer
  • 407 - the requested number of tickets is not an allowed value
  • 408 - the supplied “trolley_token” is corrupt
  • 409 - the supplied “seat_block_token” is corrupt
  • 410 - the supplied seat block is from a different price band
  • 411 - the “seat_block_offset” element is not an integer
  • 412 - the supplied seat block offset is out of range