Introduction to Booking Codes

A booking code is a textual representation of a delivery option, and it can be used to help with allocation, as follows:

As a shorthand means of instructing the metapack allocation engine exactly how you want to allocate a consignment (refer to the Allocation Service Methods of the Shipping API).
As a filter in Delivery Manager to search for the available delivery options (refer to Using a Booking Code as an Allocation Filter). For example, you could filter allocation by prefixing the required carrier 'service group' code with an @ symbol, e.g. @NEXT to search for services that deliver the next day. Refer to Example 2 below.

Booking Code Components

Let us take the following example of a booking code:

RM1STLT/2020-03-12/06:00-23:59/2020-03-13/07:00-11:59

It indicates that the delivery option to be selected is the 'Royal Mail 1st Class Letter' service, collecting on 12th March, and delivering on 13th March in the morning.

The booking code consists of five components, each separated by a forward slash ('/'):

The carrier service code, e.g. RM1STLT, or else a carrier 'service group' code (refer to Example 1 and Example 2 below, respectively).

Note

You can use our carrier library to help you identify the carrier service codes.

You can combine groups and services, by separating multiple service or group codes with commas. You can also make use of the NOT operator !, to tell the allocation engine not to consider a specific service or group. Refer to Example 7 below.

Note

You can use wild cards throughout by replacing any component, or part of a component, with the asterisk ('*') character (to represent any number of consecutive characters).

Where components following the service code or group code would otherwise consist completely of wild cards, you can omit the components. Therefore, for example, DHLNEXTDAY and DHLNEXTDAY/*/*-*/*/*-* are equivalent.
The collection date, in the format yyyy-mm-dd, or * for a wild card.
The collection window in the form of a range of times within the collection date. You can use the wild card * at either end of the range as required. Refer to the examples.
The delivery date, in the format yyyy-mm-dd, or * for a wild card.
The delivery window, in the form of a range of times within the delivery date. You can use the wild card * at either end of the range as required. Refer to the examples.

In summary, the structure is as follows:

[<carrier_service_code>|<carrier_service_group_code>|*][/<collection_date>|*][/<collection_window>|*][/<delivery_date>|*][/<delivery_window>|*]

Examples

DHLNEXTDAY/2020-01-20 will select the cheapest DHL Next Day service with a despatch date on or after 20th January 2020.
@NEXT/2020-01-20/00:01-23:59 will select the prioritised, or else cheapest, service in the NEXT carrier 'service group' that can despatch on 20th January 2020.
*/2020-01-20/00:01-23:59 will select the prioritised, or else cheapest, service that can despatch on 20th January 2020.
*/*/*-*/2020-01-20 will select the prioritised, or else cheapest, service that can deliver on or after 20th January 2020.
*/*/*-*/2020-01-20/06:00-23:59 will select the prioritised, or else cheapest, service that can deliver on 20th January 2020 between 06:00 and 23:59.
*/2020-01-20/06:00-21:00/2020-01-23/08:00-18:00 will select the prioritised, or else cheapest, service that can collect between 6:00 and 21:00 on 20th January 2020, and can deliver between 8:00 and 18:00 on 23rd January 2020.
@NEXT,!RM1STLT/*/*-*/2020-01-20/*-23:59 will select the prioritised, or else cheapest, service that is in the NEXT carrier 'service group', but is not Royal Mail First Class Letter, and can deliver on or by 20th January 2020.
@NEXT/*/*-*/2020-05-02/00:00-23:59/LATEST will select the prioritised, or else cheapest, service that is in the NEXT carrier 'service group', and can deliver by the end of 2nd May 2020. Where there is more than one service available for allocation, then the one that leaves the warehouse last will be used.

Note

If there is more than one service available for allocation, and the costs are identical, then, normally, the one that leaves the warehouse first will be selected. However, in the case of Example 8 above, we have appended /LATEST at the end, and this forces Delivery Manager to prioritise the service with the latest despatch time, allowing you to plan the packaging of the consignment in the warehouse.

If you are using Delivery Options, an API call will return the booking codes of the different delivery options (refer to the Use Case Examples in Options). You can then use the returned codes to ensure that the delivery option selected by a consumer on the web front end, is the one you use to allocate the consignment in .