If you need to quickly verify which carrier services are able to offer the best rates for delivering a proposed consignment to a consumer, within a specified delivery window while fulfilling other specific criteria, you can use findDeliveryOptionsWithBookingCode.
Note
To use this method, you need to be an API user with Delivery Options permissions. Please contact Support for more information.
No consignments are actually created or allocated using this method.
If you do not yet know all the details of the consignment, e.g. the parcelWeights, then you will need to provide estimates, by, for example, using an average weight per parcel.
The response from a successful request to findDeliveryOptionsWithBookingCode returns all the carrier services that can deliver the package, in order of shippingCost, with the cheapest first. You should therefore ensure that the correct carrier costs are set up first (refer to Setting up the Carrier Costs).
The following example API call seeks to return the carrier services within the NEXT carrier "service group" that can deliver any time on 28 August 2020 (the request has been simplified to a single parcel consignment for illustrative purposes):
<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="urn:DeliveryManager/services" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
<soapenv:Header/>
<soapenv:Body>
<ser:findDeliveryOptionsWithBookingCode soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<consignment xsi:type="typ:Consignment" xmlns:typ="urn:DeliveryManager/types">
<consignmentLevelDetailsFlag xsi:type="xsd:boolean">false</consignmentLevelDetailsFlag>
<orderNumber xsi:type="soapenc:string">T4RE345A</orderNumber>
<orderValue xsi:type="xsd:double">100</orderValue>
<parcelCount xsi:type="xsd:int">1</parcelCount>
<parcels soapenc:arrayType="ns2:Parcel[1]" xsi:type="soapenc:Array">
<parcels xsi:type="ns2:Parcel">
<cartonId xsi:type="soapenc:string">08K02JTY8</cartonId>
<code xsi:type="soapenc:string" xsi:nil="true"/>
<destinationReference xsi:type="soapenc:string" xsi:nil="true"/>
<dutyPaid xsi:type="xsd:double">0.0</dutyPaid>
<number xsi:type="xsd:int">1</number>
<originReference xsi:type="soapenc:string" xsi:nil="true"/>
<outerConsignmentCode xsi:type="soapenc:string" xsi:nil="true"/>
<outerParcelNumber xsi:type="xsd:int">0</outerParcelNumber>
<parcelDepth xsi:type="xsd:double">1.0</parcelDepth>
<parcelHeight xsi:type="xsd:double">2.0</parcelHeight>
<parcelValue xsi:type="xsd:double">20</parcelValue>
<parcelWeight xsi:type="xsd:double">2.0</parcelWeight>
<parcelWidth xsi:type="xsd:double">3.2</parcelWidth>
</parcels>
</parcels>
<recipientAddress xsi:type="ns2:Address">
<companyName xsi:type="soapenc:string">Acme Limited</companyName>
<countryCode xsi:type="soapenc:string">GBR</countryCode>
<line1 xsi:type="soapenc:string">2 Acacia Road</line1>
<line2 xsi:type="soapenc:string">London</line2>
<postCode xsi:type="soapenc:string">FX1 4AT</postCode>
</recipientAddress>
<recipientEmail xsi:type="soapenc:string">joe.public@acme.co.uk</recipientEmail>
<recipientMobilePhone xsi:type="soapenc:string">01211554975</recipientMobilePhone>
<recipientName xsi:type="soapenc:string">Joe Public</recipientName>
<senderAddress xsi:type="ns2:Address">
<companyName xsi:type="soapenc:string">Metapack</companyName>
<countryCode xsi:type="soapenc:string">GBR</countryCode>
<floor xsi:type="soapenc:string">4th Floor</floor>
<line1 xsi:type="soapenc:string">200 Grays Inn Rd</line1>
<line2 xsi:type="soapenc:string">London</line2>
<postCode xsi:type="soapenc:string">WC1X 8XZ</postCode>
</senderAddress>
<senderCode xsi:type="soapenc:string">READING1</senderCode>
<senderContactPhone xsi:type="soapenc:string">21323545</senderContactPhone>
<senderEmail xsi:type="soapenc:string">jane.doe@metapack.com</senderEmail>
<senderName xsi:type="soapenc:string">Jane Doe</senderName>
<specialInstructions1 xsi:type="soapenc:string">Leave in recycling box</specialInstructions1>
<transactionType xsi:type="soapenc:string">Delivery</transactionType>
</consignment>
<bookingCode xsi:type="soapenc:string">@NEXT/*/*-*/2020-08-28/06:00-23:59</bookingCode>
<calculateTaxAndDuty xsi:type="xsd:boolean">false</calculateTaxAndDuty>
</ser:findDeliveryOptionsWithBookingCode>
</soapenv:Body>
</soapenv:Envelope>
The response orders the carrier services in order of shippingCost, with the cheapest first:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<ns1:findDeliveryOptionsWithBookingCodeResponse soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="urn:DeliveryManager/services">
<findDeliveryOptionsWithBookingCodeReturn soapenc:arrayType="ns2:DeliveryOption[2]" xsi:type="soapenc:Array" xmlns:ns2="urn:DeliveryManager/types" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
<findDeliveryOptionsWithBookingCodeReturn xsi:type="ns2:DeliveryOption">
<bookingCode xsi:type="soapenc:string">PF01EXP24/2020-08-27/*-*/*/*-*</bookingCode>
<carrierCode xsi:type="soapenc:string">PF01</carrierCode>
<carrierCustom1 xsi:type="soapenc:string" xsi:nil="true"/>
<carrierCustom2 xsi:type="soapenc:string" xsi:nil="true"/>
<carrierCustom3 xsi:type="soapenc:string" xsi:nil="true"/>
<carrierServiceCode xsi:type="soapenc:string">PF01EXP24</carrierServiceCode>
<carrierServiceTypeCode xsi:type="soapenc:string">UNTIMED</carrierServiceTypeCode>
<collectionSlots soapenc:arrayType="ns2:DateRange[1]" xsi:type="soapenc:Array">
<collectionSlots xsi:type="ns2:DateRange">
<from xsi:type="xsd:dateTime">2020-08-27T17:30:00.000Z</from>
<to xsi:type="xsd:dateTime">2020-08-27T18:30:59.999Z</to>
</collectionSlots>
</collectionSlots>
<collectionWindow xsi:type="ns2:DateRange">
<from xsi:type="xsd:dateTime">2020-08-27T17:30:00.000Z</from>
<to xsi:type="xsd:dateTime">2020-08-27T18:30:59.999Z</to>
</collectionWindow>
<cutOffDateTime xsi:type="xsd:dateTime">2020-08-27T17:00:00.000Z</cutOffDateTime>
<deliveryLocation xsi:type="soapenc:string" xsi:nil="true"/>
<deliverySlots soapenc:arrayType="ns2:DateRange[1]" xsi:type="soapenc:Array">
<deliverySlots xsi:type="ns2:DateRange">
<from xsi:type="xsd:dateTime">2020-08-28T06:00:00.000Z</from>
<to xsi:type="xsd:dateTime">2020-08-28T16:30:59.999Z</to>
</deliverySlots>
</deliverySlots>
<deliveryWindow xsi:type="ns2:DateRange">
<from xsi:type="xsd:dateTime">2020-08-28T06:00:00.000Z</from>
<to xsi:type="xsd:dateTime">2020-08-28T16:30:59.999Z</to>
</deliveryWindow>
<groupCodes soapenc:arrayType="soapenc:string[1]" xsi:type="soapenc:Array">
<groupCodes xsi:type="soapenc:string">NEXT</groupCodes>
</groupCodes>
<name xsi:type="soapenc:string">Express 24</name>
<nominatableCollectionSlot xsi:type="xsd:boolean">false</nominatableCollectionSlot>
<nominatableDeliverySlot xsi:type="xsd:boolean">false</nominatableDeliverySlot>
<recipientTimeZone xsi:type="soapenc:string">Europe/London</recipientTimeZone>
<score xsi:type="xsd:double">1.0</score>
<senderTimeZone xsi:type="soapenc:string">Europe/London</senderTimeZone>
<shippingCharge xsi:type="xsd:double">12.0</shippingCharge>
<shippingCost xsi:type="xsd:double">3.5</shippingCost>
<taxAndDuty xsi:type="xsd:double">0.0</taxAndDuty>
<taxAndDutyStatusText xsi:type="soapenc:string" xsi:nil="true"/>
<vatRate xsi:type="xsd:double">0.0</vatRate>
</findDeliveryOptionsWithBookingCodeReturn>
<findDeliveryOptionsWithBookingCodeReturn xsi:type="ns2:DeliveryOption">
<bookingCode xsi:type="soapenc:string">HERMNDG/2020-08-27/*-*/*/*-*</bookingCode>
<carrierCode xsi:type="soapenc:string">HERMESPOS</carrierCode>
<carrierCustom1 xsi:type="soapenc:string" xsi:nil="true"/>
<carrierCustom2 xsi:type="soapenc:string" xsi:nil="true"/>
<carrierCustom3 xsi:type="soapenc:string" xsi:nil="true"/>
<carrierServiceCode xsi:type="soapenc:string">HERMNDG</carrierServiceCode>
<carrierServiceTypeCode xsi:type="soapenc:string">UNTIMED</carrierServiceTypeCode>
<collectionSlots soapenc:arrayType="ns2:DateRange[1]" xsi:type="soapenc:Array">
<collectionSlots xsi:type="ns2:DateRange">
<from xsi:type="xsd:dateTime">2020-08-27T17:30:00.000Z</from>
<to xsi:type="xsd:dateTime">2020-08-27T18:30:59.999Z</to>
</collectionSlots>
</collectionSlots>
<collectionWindow xsi:type="ns2:DateRange">
<from xsi:type="xsd:dateTime">2020-08-27T17:30:00.000Z</from>
<to xsi:type="xsd:dateTime">2020-08-27T18:30:59.999Z</to>
</collectionWindow>
<cutOffDateTime xsi:type="xsd:dateTime">2020-08-27T17:00:00.000Z</cutOffDateTime>
<deliveryLocation xsi:type="soapenc:string" xsi:nil="true"/>
<deliverySlots soapenc:arrayType="ns2:DateRange[1]" xsi:type="soapenc:Array">
<deliverySlots xsi:type="ns2:DateRange">
<from xsi:type="xsd:dateTime">2020-08-28T07:00:00.000Z</from>
<to xsi:type="xsd:dateTime">2020-08-28T19:00:59.999Z</to>
</deliverySlots>
</deliverySlots>
<deliveryWindow xsi:type="ns2:DateRange">
<from xsi:type="xsd:dateTime">2020-08-28T07:00:00.000Z</from>
<to xsi:type="xsd:dateTime">2020-08-28T19:00:59.999Z</to>
</deliveryWindow>
<groupCodes soapenc:arrayType="soapenc:string[2]" xsi:type="soapenc:Array">
<groupCodes xsi:type="soapenc:string">PLNEXTDAY</groupCodes>
<groupCodes xsi:type="soapenc:string">NEXT</groupCodes>
</groupCodes>
<name xsi:type="soapenc:string">Courier Service Next Day</name>
<nominatableCollectionSlot xsi:type="xsd:boolean">false</nominatableCollectionSlot>
<nominatableDeliverySlot xsi:type="xsd:boolean">false</nominatableDeliverySlot>
<recipientTimeZone xsi:type="soapenc:string">Europe/London</recipientTimeZone>
<score xsi:type="xsd:double">1.0</score>
<senderTimeZone xsi:type="soapenc:string">Europe/London</senderTimeZone>
<shippingCharge xsi:type="xsd:double">11.0</shippingCharge>
<shippingCost xsi:type="xsd:double">7.7</shippingCost>
<taxAndDuty xsi:type="xsd:double">0.0</taxAndDuty>
<taxAndDutyStatusText xsi:type="soapenc:string" xsi:nil="true"/>
<vatRate xsi:type="xsd:double">0.0</vatRate>
</findDeliveryOptionsWithBookingCodeReturn>
</findDeliveryOptionsWithBookingCodeReturn>
</ns1:findDeliveryOptionsWithBookingCodeResponse>
</soapenv:Body>
</soapenv:Envelope>
You can experiment by adjusting the parcel's weight, dimensions and value in the following fields, and then rerunning the request as required:
<parcelDepth xsi:type="xsd:double">1.0</parcelDepth>
<parcelHeight xsi:type="xsd:double">2.0</parcelHeight>
<parcelValue xsi:type="xsd:double">20</parcelValue>
<parcelWeight xsi:type="xsd:double">2.0</parcelWeight>
<parcelWidth xsi:type="xsd:double">3.2</parcelWidth>
Provided that the Carrier Allocation Rules have been set up appropriately, different carrier services and costs should be returned when the request is rerun with different parcel values.
Once you have used the returned delivery options to determine the carrier service to which you want to allocate the consignment, go to either createAndAllocateConsignmentsWithBookingCode or despatchConsignmentWithBookingCode, where you can copy and paste the body of the consignment from the call that you have just made.
When entering the booking code to allocate the consignment, you can now simply copy the booking code for the preferred delivery option from the response to findDeliveryOptionsWithBookingCode (see the following example).
<bookingCode xsi:type="soapenc:string">PF01EXP48/*/*-*/2020-08-28/06:00-23:59</bookingCode>