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

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

14.1.1. Example input

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

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

14.2.1. Example output

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

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