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.

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.

  1. Prioritised service (if one has been selected automatically via the Carrier Allocation Rules).

  2. Shipping cost (the system will always try and select the cheapest service where there is no prioritised service).

  3. Earliest despatch (if two services cost the same, the one that leaves the warehouse first will be chosen).

  4. 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:

  1. If it's an array, add the required <items>.

  2. Otherwise, replace the '?' with the appropriate response. Where there is a Boolean type, replace it with either true or false.

Table 6. Advanced Allocation Filter Properties

Property Name

Type

Manda- tory?

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>