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:

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 ('/'):

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

  2. The collection date, in the format yyyy-mm-dd, or * for a wild card.

  3. The collection window, in the form of a date/time range, with * for a wild card at either end of the range, as required. For example:

    1. 2020-02-24T18:30:00.000Z-2020-02-24T19:30:59.999Z

    2. 2020-02-24-2020-02-25

    3. *-2020-02-25T19:30:59.999Z

    4. 2020-02-24-*

    5. *-*

    Note

    It is possible to specify a time without a preceding date in the collection window but only if there is a specific collection date. Refer to Example 6 below.

  4. The delivery date, in the format yyyy-mm-dd, or * for a wild card.

  5. The delivery window, in the form of a date/time range, with * for a wild card as required. Refer to the collection window for examples.

    Note

    It is possible to specify a time without a preceding date in the delivery window but only if there is a specific delivery date. Refer to Example 5 below.

In summary, the structure is as follows:

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

Examples

  1. DHLNEXTDAY/2020-01-20 will select the cheapest DHL Next Day service with a despatch date on or after 20th January 2020.

  2. @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.

  3. */2020-01-20/00:01-23:59 will select the prioritised, or else cheapest, service that can despatch on 20th January 2020.

  4. */*/*-*/2020-01-20 will select the prioritised, or else cheapest, service that can deliver on or after 20th January 2020.

  5. */*/*-*/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. The acceptable delivery dates are constructed from the times in the window set against the date provided. Therefore, in this example the two acceptable dates used in the allocation filter are 2020-01-20T06:00 and 2020-01-20T23:59.

  6. */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.

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

  8. @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 Delivery Manager.