The *trolley\_add\_order* method
================================

This method is used to bundle single orders into a single block known as
a "trolley". It is this trolley which is the unit used to reserve and
then purchase orders. This method takes an order token and an optional
trolley token and adds the order to the trolley. If no trolley token is
supplied then a new empty trolley is created for the order to be added
to. Not all orders may be mixed with all other orders for a variety of
reasons, and thus this method may not always succeed. In the situation
where the order cannot be added then a set of elements is returned
indicating the reasons why the operation could not be performed.
Attempts to add an order for the same event on the same date twice to a
trolley will succeed, but will result in the original order being
replaced. The number of items in the trolley is returned as part of the
output, so it is easy to detect if this has occurred. For ease of
developing a client for the code, it is possible for this method to
include a description of the new trolley at the output following a
successful addition, via the use of a single input element. Orders which
have been added to a trolley are assigned a unique item number, which is
never re-used during the lifetime of a single trolley. This item number
provides a reference through which an order within a trolley can be
identified for such purposes as removal.

Required inputs
---------------

A "crypto\_block" from "start\_session" method must be present. This may
come from the original "start\_session" or may be one of the crypto
blocks produced from any of the other methods which are documented as
generating a "start\_session" compatible block. In particular the output
of "create\_order" and all the trolley modifying methods (including this
one) produce such a block. An "order\_token" must be present. An
optional "describe\_trolley" element may also be present if the full
trolley contents are required in the output result. The contents of this
element are irrelevant as it is merely its presence which is taken into
account.

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

.. code-block:: xml

    <trolley_add_order>
    <user_id>demo</user_id>
    <crypto_block>U_--LfP7rp3MoitCr2ofVaNShLkdOlMurxfADnkYLSOFxUoQo
    YUZz_Kq23SaaVvPmF43Ndbq2o1t5Nq60tvNucAoeiun5eRalXx5Tz-H7Q7UreSD
    lXCTGZEvwqddnGIUevnZY</crypto_block>
    <order_token>E1--_mjRuXT_ko3XfykAhrLF2pU83_vWRy2eo2GoU9KOeM8D7b
    UtQfbYDKQI5wjcXNkQTawn1t0Uky8dHP9v_uT5yWNr361OuYUEhOa3xJVCr7zMH
    s58F-3to-nZ7djPUY085aJnq4PTKDRFizaLrId_Sy6HlIw76yy3KcJEHCAAydxf
    SMrtV4Mx3uLcWGX5DUzFnXs4MId_FllMAqUksPTnn9npgn7LybccDxU0pai2HJ4
    IwJ6rJkvmEeoreJIIHKrSeeQzfUY483T1upBF445xK_--Z</order_token>
    </trolley_add_order>

Output data
-----------

The output data from the method always contains an "add\_possible"
element with is a either "yes" or "no". This indicates whether the
addition of the order into the trolley was possible or not. Where an
addition cannot be performed there are additional elements provided, all
beginning with the prefix "trolley\_bad\_", which are used to indicate
the reason for the failure. There are seven of these elements, and all
of them are always present in the output, each one containing either a
"yes" or a "no" value. There may be more than one reason why an addition
cannot be made, and thus it is not necessarily the case than only a
single element will have a "yes" value. For some of the elements there
will be additional elements added in the case of a "yes" to indicated
more detailed information about the reason for the failure. The seven
failure reasons are as follows:

- **trolley\_bad\_bundle**

   A single supplier of tickets may only bundle up to a certain number
   of orders at any one time (this may be "one" for systems which do not
   support the concept of trolleys). This element indicates that no more
   orders for the particular supplier may be added to the trolley. An
   extra element "trolley\_bad\_bundle\_max\_size" will be present if
   this is true, which contains an integer indicating the maximum number
   of allowable orders from this supplier which may be placed in the
   trolley.

- **trolley\_bad\_combo**

   Some users are allowed to mix tickets from different suppliers in the
   same trolley, and some are not. This element indicates that the
   mixing of different suppliers is not allowed, and that the order you
   are attempting to add is from a different supplier to those already
   in the trolley. If this is true the extra elements
   "trolley\_bad\_combo\_system" and "trolley\_bad\_combo\_system\_desc"
   will be present describing the existing supplier. The first holds the
   code for the ticket supplier, and the second the textual description
   of the supplier. These are the same code and text normally referred
   to as "source\_code" and"source\_desc" in other parts of the XML
   core.

- **trolley\_bad\_card\_types**

   Each supplier of tickets has a certain list of card types which are
   accepted for payment. This element indicates that there are no cards
   accepted by the supplier of the current order that are also accepted
   by the suppliers of the orders already in the trolley. As a single
   payment card is taken for purchase of the entire trolley then it is
   necessary that there is at least one acceptable card type in common
   across all the various suppliers in the trolley.

- **trolley\_bad\_countries**

   Some despatch methods that require delivery of the tickets to the
   customer are restricted to a certain list of countries to which they
   may be sent. This element indicates that the current order has a list
   of countries which does not overlap with the list of countries in the
   current trolley. As only a single delivery address is collected for
   despatch, then there needs to be at least one acceptable country in
   common across all suppliers in the trolley. This is a very similar
   restriction to the preceeding card type restriction.

- **trolley\_bad\_currency\_mix**

   A single bundle of tickets from one of the ticket suppliers is
   purchased using a single debit on the payment card. For this reason
   all orders from a particular supplier must be priced in the same
   currency. This element indicates that there are already orders
   present from this supplier in the trolley, and that these orders are
   priced in a different currency to the current order. The elements
   "trolley\_bad\_currency\_system" and
   "trolley\_bad\_currency\_system\_desc" hold the code and description
   of the ticket supplier, in the same way as for the
   "trolley\_bad\_combo" element. In addition the actual currency
   details for the existing supplier are present in the elements
   "trolley\_bad\_currency" and "trolley\_bad\_currency\_name" etc,
   carrying all the information usually associated with a currency, but
   with the prefix "trolley\_bad\_". The usual codes, places and symbols
   are all present.

- **trolley\_bad\_depart**

   Some orders require a departure date to be specified for various
   reasons, usually related to despatch of tickets. A trolley needs to
   have a single departure date for all tickets from all suppliers, and
   thus this element indicates that the current order has a different
   departure date to the orders already in the trolley. This restriction
   only applies to orders which need a departure date. Orders without
   may be freely combined with orders that do have a date.

- **trolley\_bad\_send**

   A bundle of orders from a single supplier is purchased as a single
   transaction, and thus has a single despatch method applied to all of
   the orders. This element indicates that the current order has a
   different basic despatch (a.k.a "send") type from those already in
   the trolley from this supplier. This restriction can be avoided by
   passing in the current trolley to the "availability\_options" method
   as this will result in only those despatch methods which are
   allowable being returned.

Where the "add\_possible" element contains a "yes" value then the
trolley addition has succeeded. A "start\_session" compatible
"crypto\_block" element is produced which may be used as input for any
of the other trolley manipulating methods, plus a token for the new
trolley in the element "trolley\_token". Additions does not always
result in an increase in the number of items in the trolley, as only a
single instance of a particular event on a particular date my be
purchased, and thus an addition of another order for the same event on
the same date will result in the original being replaced. The number of
orders in the new trolley is always available in the element
"trolley\_order\_count" following a successful addition. The item number
allocated to the newly added order is available in the
"added\_item\_number" element.

If the "describe\_trolley" element was present in the input request then
a complete description of the trolley will be found in the element
"trolley". For documentation on this please refer to the
"trolley\_describe" method.

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

.. code-block:: xml

    <trolley_add_order_result>
    <crypto_block>U_--LfP7rp3MoitCr2ofVaNShLkdOlMurxfADnkYLSOFxUoQo
    YUZz_Kq23SaaVvPmF43Ndbq2o1t5Nq60tvNucAoeeRLZptl3ybUpxBT61BnuGMD
    lXCTGZEvwqddnGIUevnZY</crypto_block>
    <add_possible>yes</add_possible>
    <trolley_token>k1---IHQgb4xt2KimGiw-fPma5Oh1PFVyQJAx1hTrvv60DMz
    73WJH8WgUVjBoxB5BLQo9pEilPGEmlk0uVX1Xb5gdejnDvVPYmf205VUlPVYwtd
    zGfr1vBNznQp8OYLwx7kwNbQAFbcF_KlquVRXGLIH9YFGQARVJWGGLUDixXEkyq
    fsF7DLEHd6kJYTaN0jzPGMMLdWsMIh1Nnms4jrDs1vzjUBVrv_uNX0CK4ezWxgp
    jy1toCmQ-aWcrxkO7N-U1-Z9HX44b1CWwXDXVxecEhDjSUPrcKIB0Y6ZaHQABER
    XTyMSsp3j4SZ36ESZjbOP8PfZ</trolley_token>
    <trolley_order_count>1</trolley_order_count>
    <added_item_number>0</trolley_order_count>
    </trolley_add_order_result>

Potential failure codes
-----------------------

- **1** - the supplied crypto block was not generated by
   "start\_session"

- **2** - the requested "mime\_text\_type" was not a supported value

- **601** - no "order\_token" has been supplied

- **602** - the supplied "order\_token" is corrupt

- **603** - the supplied "trolley\_token" is corrupt

- **604** - the trolley has already been purchased

- **605** - the trolley has already been reserved