/
Reservation Examples

Reservation Examples

Owned by Člen AB týmu
Last updated: 26 Aug 2024
7 min read

Contents of the page:

Lets take a look at some examples to better demonstrate this functionality. We will start with the very basic ones and move on to the more difficult ones.

Please note that the examples below use a non-existent pkgSize attribute to simplify the scenarios. In a real world example, the package size is calculated based on the supplied dimensions!

1. Basic scenarios

Example 1. 1. - Basic scenario for combination of classic reservation + prereservation

Request is made to our API with following body:

POST /parcel-lockers/v2/reservation { "data": { "reservation": { "id": "RES_1_1", "attributes": { "startReservationDate": "2024-06-14T06:00:00.000Z", "expirationDate": "2024-06-16T06:00:00.000Z", "nextReservationTimes": [ { "startReservationDate": "2024-06-15T06:00:00.000Z", "expirationDate": "2024-06-17T06:00:00.000Z", "prereservationExpirationDate": "2024-06-15T02:00:00.000Z", }, ], "pkgSize": "S", "type": "TIME" }, "relationships": { "box": { "id": 1 } } } } }

What the algorithm does is it will first check whether a reservation can be made for the times specified on lines 7 and 8.

Several scenarios can occur:

a. Classic Reservation can be created with status RESERVED for the first time slot

The reservation can be created, thus we create it with status RESERVED and you receive immediate response (as with standard behaviour for reservations).

b. Reservation can be created with status RESERVED for the second time slot

The reservation can be created for the second time slot, thus we create it with status RESERVED and you receive immediate response.

c. Only Prereservation can be created

Reservation cannot be created for neither time slot, since the desired box is full. The system will create a prereservation for the second time slot defined by lines 11 and 12 limited by the deadline specified on line 13 (note the first time slot is ignored for prereservation, because there is no prereservationExpirationDate attribute). You will receive immediate response with status PRERESERVED.

  • Should the desired box free up before the deadline (prereservationExpirationDate), you will receive a callback indicating the change of the status from PRERESERVED to RESERVED.

  • Should the desired box not free up before the deadline, you will receive a callback indicating the change of the status from PRERESERVED to EXPIRED meaning the prereservation has expired.

Example 1. 2. - Basic scenario for prereservation

Request is made to our API with following body:

POST /parcel-lockers/v2/reservation { "data": { "reservation": { "id": "RES_1_1", "attributes": { "startReservationDate": "2024-06-14T06:00:00.000Z", "expirationDate": "2024-06-16T06:00:00.000Z", "prereservationExpirationDate": "2024-06-14T02:00:00.000Z", "nextReservationTimes": [ { "startReservationDate": "2024-06-15T06:00:00.000Z", "expirationDate": "2024-06-17T06:00:00.000Z", "prereservationExpirationDate": "2024-06-15T02:00:00.000Z", }, ], "pkgSize": "S", }, "relationships": { "box": { "id": 1 } } } } }

What the algorithm does is it will first check whether a reservation can be made for the times specified on lines 7 and 8.

Several scenarios can occur:

a. Classic Reservation can be created with status RESERVED for the first time slot

The reservation can be created for the first time slot, thus we create it with status RESERVED and you receive immediate response.

b. Classic Reservation can be created with status RESERVED for the second time slot

The reservation can be created for the second time slot, thus we create it with status RESERVED and you receive immediate response.

c. Prereservation can be created for the first time slot

Reservation could not be created for neither first nor second time slot. The system will then create reservation wit status PRERESERVED for the first time slot limited by the deadline.

Following scenarios can occur:

c. 1. Space is freed up before the 1st deadline

Should the desired box free up before the deadline (prereservationExpirationDate), you will receive callback indicating the change of the status from PRERESERVED to RESERVED.

c. 2. Space is not freed up before the 1st deadline

Should the desired box not free up, the next time slot is used and prereservation time slot changes and you will receive a callback indicating the time slot change.

c. 3. Space is freed up before the 2nd deadline

Should the desired box free up before the 2nd deadline (prereservationExpirationDate), you will receive callback indicating the change of the status from PRERESERVED to RESERVED.

c. 4. Space is not freed up before the 2nd deadline

The reservation expires and you will receive callback indicating status change from PRERESERVED to EXPIRED.

2. Advanced scenarios

Example 2. 1. - First time slot could not be satisfied + reservation time slot change

Request is made to our API with following body:

POST /parcel-lockers/v2/reservation {   "data": {     "reservation": {       "id": "RES_1_1",       "attributes": {        "startReservationDate": "2024-06-14T06:00:00.000Z",        "expirationDate": "2024-06-16T06:00:00.000Z",        "prereservationExpirationDate": "2024-06-14T02:00:00.000Z",         "nextReservationTimes": [           {             "startReservationDate": "2024-06-15T06:00:00.000Z",             "expirationDate": "2024-06-17T06:00:00.000Z",             "prereservationExpirationDate": "2024-06-15T02:00:00.000Z",           },         ],        "pkgSize": "S",       },       "relationships": {        "box": {          "id": 1        }       }     }   } }

The algorithm checks whether a reservation can be created for the first time slot (lines 7 and 8).

It is determined, that the reservation cannot be created, thus the algorithm checks for additional supplied timeslots inside the nextReservationTimes attribute. The earliest time slot from the array is fetched (lines 12 and 13 in this case) and again it is determined, whether a reservation can be created or not.

The reservation can be created, thus we create it and you receive a response with status RESERVED for the time slot on lines 12 and 13.

However we keep the first time slot (lines 7 and 8) saved in case a space in a box is freed up for such time slot considering the size of your package. It is important to know that the supplied prereservationExpirationDate on line 9 determines the time until which you are able to accept the time slot change.

Let’s say a space frees up in the desired Box 1, which unblocks your desired time slot (lines 7 and 8). In this case this event took place before 14. 6. 2024 2AM (defined by you on line 9).

What the algorithm does is it will check all PRERESERVED or RESERVED (with earlier not satisfied time slots), ordered by the first come first server principle. In this case let’s say your reservation is the first candidate. It will check whether a reservation can be created for the first time slot (lines 7 and 8).

The reservation can be created, so the algorithm changes your reservation’s time slot from 15. 6. 2024 -17. 6. 2024 to 14. 6. 2024 - 16. 6. 2024. Then we send you callback with the time slot change.

You can check following visualization of the process for this example:

image-20240614-071732.png

Example 2. 2. - prereservation scenario

Request is made to our API with following body:

POST /parcel-lockers/v2/reservation {   "data": {     "reservation": {       "id": "RES_1_1",       "attributes": {        "startReservationDate": "2024-06-14T06:00:00.000Z",        "expirationDate": "2024-06-16T06:00:00.000Z",        "prereservationExpirationDate": "2024-06-14T02:00:00.000Z",         "nextReservationTimes": [           {             "startReservationDate": "2024-06-15T06:00:00.000Z",             "expirationDate": "2024-06-17T06:00:00.000Z",             "prereservationExpirationDate": "2024-06-15T02:00:00.000Z",           },         ],        "pkgSize": "S",       },       "relationships": {        "box": {          "id": 1        }       }     }   } }

The algorithm checks whether a reservation can be created for the first time slot (lines 7 and 8).

It is determined, that the reservation cannot be created, thus the algorithm checks for additional supplied timeslots inside the nextReservationTimes attribute. The earliest time slot from the array is fetched (lines 12 and 13 in this case) and again it is determined, whether a reservation can be created or not.

The reservation cannot be created, thus we create a PRERESERVATION for the earliest time slot (lines 7 and 9).

You receive the expected answer, however with status PRERESERVED. This prereservation is kept in our system until one of the following conditions occures:

  • the prereservation expires (the time now > prereservationExpirationDate supplied by you on line 9) - in this case we would change the time slot for the second time slot supplied in the nextReservationTimes attribute and you would receive a callback with the time slot change.

  • space in a box 1 is freed up for the desired time slot - in this case we would try to create the reservation for the time slot. In case of success, you would receive a callback with the status changed to RESERVED.

Let’s say the second condition is met, thus a space frees up in the desired Box 1, which unblocks your desired time slot (lines 7 and 8). In this case this event took place before 14. 6. 2024 2AM (defined by you on line 9).

What the algorithm does is it will check all PRERESERVED or RESERVED (with earlier not satisfied time slots), ordered by the first come first server principle. In this case let’s say your reservation is a second candidate. So it will take a different reservation from a different partner, which we received as a request before yours. It will check whether the reservation can be created for that parner.

Let’s say it could not be created, because the freed up space (for example cancelled package) was for a package of size S and the second partner’s package size is L. The algorithm could not fit such reservation, so it will look for the next candidate, which in this case is your reservation.

The reservation can be created in this case, so the algorithm changes your reservation’s status from PRERESERVED to RESERVED. Then we send you callback with the status change.

You can check following visualization of the process for this example:

image-20240614-071819.png

 

Related content