Booking Codes and the Allocation Filter

There are two different ways of allocating a consignment: using a booking code or the advanced allocation filter.

The means of allocation is dependent on the nature of the call, i.e.

If the call contains BookingCode as part of the title, e.g. despatchConsignmentWithBookingCode, createAndAllocateConsignmentsWithBookingCode, allocateConsignmentsWithBookingCode or debugConsignmentWhyNotWithBookingCode, then you need to specify a booking code.
Otherwise, use the advanced allocation filter, as with the following calls: despatchConsignment, createAndAllocateConsignments, allocateConsignments and debugConsignmentWhyNot.

Note

If you omit the means of allocation in the call, then allocation can still proceed, but it will follow the default Delivery Manager allocation hierarchy, i.e.

Prioritised service (if one has been selected automatically via the Carrier Allocation Rules).
Shipping cost (the system will always try and select the cheapest service where there is no prioritised service).
Earliest despatch (if two services cost the same, the one that leaves the warehouse first will be chosen).
Earliest delivery (if two services cost the same and leave the warehouse at the same time, the one that can deliver first is selected),

The use of booking codes is recommended wherever possible because they are more straightforward than the more complex advanced allocation filter. Booking codes also provide more consistency, particularly when used in conjunction with carrier 'service groups'.

Tip

You may find the advanced allocation filter useful if you are delivering to service points and wish to specify a PUDO radius.

Booking Codes

For example, you can specify a carrier service code and delivery window:

...
<consignments xsi:type="soapenc:Array" soapenc:arrayType="tns1:Consignment[1]">
...
</consignments>
<bookingCode xsi:type="soapenc:string">HERMNDG/*/*-*/2020-08-13/00:01-23:59</bookingCode>
...

Or use a carrier 'service group' by prefacing it with @:

...
<consignments xsi:type="soapenc:Array" soapenc:arrayType="tns1:Consignment[1]">
...
</consignments>
<bookingCode xsi:type="soapenc:string">@NEXT</bookingCode>
...

Note

For a full explanation with further examples, refer to Introduction to Booking Codes.

Advanced Allocation Filter

All the filter properties are optional. If any are not required, simply remove them completely, or, in the case of an array, ignore them.

For each property that you wish to use:

If it's an array, add the required <items>.
Otherwise, replace the '?' with the appropriate response. Where there is a Boolean type, replace it with either true or false.

Table 21. Advanced Allocation Filter Properties

Property Name	Type	Description
`pudoRadius`	`integer`	The radius in metres for a PUDO and 'Click and Collect' store search. In order to use this property, you need to be an API user with Delivery Options permissions. Please contact Support for more information. If a value is not specified, then the value configured within Delivery Manager for the metapack.locationservices.radius.maxvalue property will be used.
`acceptableCarrierCodes`	array of type`string`	An array of possible carrier codes that can be used for allocating the particular consignment.
`acceptableCarrierServiceCodes`	array of type`string`	An array of possible carrier service codes that can be used for allocating the particular consignment.
`acceptableCarrierServiceGroupCodes`	array of type`string`	An array of possible carrier 'service group' codes that can be used for allocating the particular consignment.
`acceptableCarrierServiceTypeCodes`	array of type`string`	An array of possible service type codes, e.g. a selection from UNTIMED, ECONOMY, TIMED and EVENING, that can be used for allocating the particular consignment.
`acceptableCollectionDays`	array of type`WorkingDays`	Set a WorkingDay to true if collection is possible on that day. Otherwise, set it to false.
`acceptableCollectionSlots`	array of type`DateRange`	The from...to range of dateTime values within which collection is possible. You can leave either the from or to value empty.
`acceptableDeliveryDays`	array of type`DateRange`	Set a WorkingDay to true if delivery is possible on that day. Otherwise, set it to false.
`acceptableDeliverySlots`	array of type`DateRange`	The from...to range of dateTime values within which delivery is possible. You can leave either the from or to value empty.
`expandGroups`	`boolean`	If a carrier service is in multiple carrier 'service groups', then setting this property to true returns one distinct delivery option per group, as opposed to a single option with all the groups in it. The default is false.
`filterGroup1`	`integer`	You can add up to three filter group codes, which are integers referring to types of delivery option. Adding one will discard all the options except the first one, for that particular type. For example, if you add a filterGroup with a code of 2 (Group by carrier service), and there are two options for the same carrier service ID, then only the first one will be returned.
`filterGroup2`
`filterGroup3`
`firstCollectionOnly`	`boolean`	For optimisation, you can set this to true in order to restrict your search to the earliest despatch for a carrier service. The default is false.
`maxAnalysisDayCount`	`integer`	The maximum number of despatch days onward from the current date that can be considered (the default is 60). You should be able to limit this number automatically by the correct use of the other filter properties.
`maxCost`	`double precision floating point number`	Setting this service to a value other than the default of zero, ensures that any service costing the same as, or more than the specified value, will be disregarded.
`maxDatesPerService`	`integer`	This is the maximum number of delivery windows that can be returned for a carrier service.
`maxScore`	`double precision floating point number`	Setting this value ensures that any carrier service that has an overall calculated score above this value will be disregarded.
`minScore`	`double precision floating point number`	Setting this value ensures that any carrier service that has an overall calculated score below this value will be disregarded.
`preFilterSortOrder1`	`integer`	A list of up to three sort order codes, in order of priority. Each integer refers to a type of sort that is to take place before any filters are applied. You might, for example, choose to pre-filter carrier services by code 2 (Ascending sort by earliest collection date and time), then by code 15 (Cutoff date and time, earliest first), and, finally, by code 13 (Sort by score, lowest first),
`preFilterSortOrder2`
`preFilterSortOrder3`
`sortOrder1`	`integer`	A list of up to three sort order codes, in order of priority. Each integer refers to a type of sort that is to take place after the other filters have been applied. You might, for example, choose to sort the final results in order of cost within carrier 'service group'. To do this, use code 17 (Ascending sort by carrier 'service group' code), and then code 6 (Sort by cost, cheapest first).
`sortOrder2`
`sortOrder3`
`unacceptableCarrierCodes`	array of type`string`	An array of possible carrier codes that are not to be used for allocating the particular consignment.
`unacceptableCarrierServiceCodes`	array of type`string`	An array of possible carrier service codes that are not to be used for allocating the particular consignment.
`unacceptableCarrierServiceGroupCodes`	array of type`string`	An array of possible carrier 'service group' codes that are not to be used for allocating the particular consignment.
`unacceptableCarrierServiceTypeCodes`	array of type`string`	An array of possible service type codes, e.g. a selection from `UNTIMED`, `ECONOMY`, `TIMED` and `EVENING`, that are not to be used for allocating the particular consignment.
`unacceptableCollectionDays`	array of type`WorkingDays`	Set a WorkingDay to true if collection is not possible on that day. Otherwise, set it to false.
`unacceptableCollectionSlots`	array of type`DateRange`	The from...to range of dateTime values within which collection is not possible. You can leave either the from or to value empty.
`unacceptableDeliveryDays`	array of type`DateRange`	Set a WorkingDay to true if delivery is not possible on that day. Otherwise, set it to false.
`unacceptableDeliverySlots`	array of type`DateRange`	The from...to range of dateTime values within which delivery is not possible. You can leave either the from or to value empty.

In the following example, the aim of the filter is to return options for an acceptable collection slot any time after 31 July 2020 15:20 hours. There is a pre-filter sort of the returned options by sort code 2 (Ascending sort by earliest collection date and time). The options are then filtered by filter code 2 (Group by carrier service) to return one option only for each service. The options are finally sorted by code 6 (Sort by cost, cheapest first).

<filter xsi:type="typ:AllocationFilter" xmlns:typ="urn:DeliveryManager/types">
            <!--Optional:-->
            <pudoRadius xsi:type="xsd:int">400</pudoRadius>
   <acceptableCarrierCodes xsi:type="soapenc:string" xsi:nil="true" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"/>
   <acceptableCarrierServiceCodes xsi:type="soapenc:string" xsi:nil="true" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"/>
    <acceptableCarrierServiceGroupCodes xsi:type="ser:ArrayOf_soapenc_string" soapenc:arrayType="soapenc:string[]">  
            <item>NEXT</item>
   </acceptableCarrierServiceGroupCodes>
   <acceptableCarrierServiceTypeCodes xsi:type="soapenc:string" xsi:nil="true" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"/>
   <acceptableCollectionDays xsi:type="ns3:WorkingDays" xsi:nil="true"/>
   <acceptableCollectionSlots soapenc:arrayType="ns3:DateRange[1]" xsi:type="soapenc:Array" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
      <item xsi:type="ns3:DateRange">
         <from xsi:type="xsd:dateTime">2020-07-30T15:20:23.730Z</from>
         <to xsi:type="xsd:dateTime" xsi:nil="true"/>
      </item>
   </acceptableCollectionSlots>
   <acceptableDeliveryDays xsi:type="ns3:WorkingDays" xsi:nil="true"/>
   <acceptableDeliverySlots xsi:type="ns3:DateRange" xsi:nil="true"/>
   <expandGroups xsi:type="xsd:boolean">false</expandGroups>
   <filterGroup1 xsi:type="xsd:int">2</filterGroup1>
   <filterGroup2 xsi:type="xsd:int">0</filterGroup2>
   <filterGroup3 xsi:type="xsd:int">0</filterGroup3>
   <firstCollectionOnly xsi:type="xsd:boolean">true</firstCollectionOnly>
   <maxAnalysisDayCount xsi:type="xsd:int">0</maxAnalysisDayCount>
   <maxCost xsi:type="xsd:double">0.0</maxCost>
   <maxDatesPerService xsi:type="xsd:int">0</maxDatesPerService>
   <maxScore xsi:type="xsd:double">0.0</maxScore>
   <minScore xsi:type="xsd:double">0.0</minScore>
   <preFilterSortOrder1 xsi:type="xsd:int">2</preFilterSortOrder1>
   <preFilterSortOrder2 xsi:type="xsd:int">0</preFilterSortOrder2>
   <preFilterSortOrder3 xsi:type="xsd:int">0</preFilterSortOrder3>
   <sortOrder1 xsi:type="xsd:int">6</sortOrder1>
   <sortOrder2 xsi:type="xsd:int">0</sortOrder2>
   <sortOrder3 xsi:type="xsd:int">0</sortOrder3>
   <unacceptableCarrierCodes xsi:type="soapenc:string" xsi:nil="true" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"/>
   <unacceptableCarrierServiceCodes xsi:type="soapenc:string" xsi:nil="true" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"/>
   <unacceptableCarrierServiceGroupCodes xsi:type="soapenc:string" xsi:nil="true" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"/>
   <unacceptableCarrierServiceTypeCodes xsi:type="soapenc:string" xsi:nil="true" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"/>
   <unacceptableCollectionDays xsi:type="ns3:WorkingDays" xsi:nil="true"/>
   <unacceptableCollectionSlots xsi:type="ns3:DateRange" xsi:nil="true"/>
   <unacceptableDeliveryDays xsi:type="ns3:WorkingDays" xsi:nil="true"/>
   <unacceptableDeliverySlots xsi:type="ns3:DateRange" xsi:nil="true"/>
</filter>