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.

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.

Example input
~~~~~~~~~~~~~

.. code-block:: xml

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

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.

Example output
~~~~~~~~~~~~~~

.. code-block:: xml

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

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