/
Prereservation

Prereservation

Owned by Člen AB týmu
Last updated: 18 Oct 2024
5 min read

Although not a requirement, to take full advantage of this new functionality it is strongly recommended to implement it in conjuction with the “Next Reservation Times”, see Next reservation times for Time reservation.

Contents of the page:

Examples:

Related pages:

Prereservation updates

API Change protocol - 20231110 - NextReservationTimes input parameter

Callback for reservation change state

Description

The purpose of this functionality is to allow partners to create a prereservation, which can wait in such state (API status attribute) for a specified amount of time. By doing so, it is unnecessary to make the same reservation call several times, but rather wait for a callback, which can indicate the expiration of the prereservation (the prereservation failed due to set time interval for its validity) or its success.

The functionality is based on sort of a queue with first come first served in mind. This means that the first prereservation request to arrive in the queue is guaranteed to be dealt with as a first candidate, when a space is freed in desired box (having reservation package size in mind). No other partner can be served before this prereservation is checked. In case the prereservation cannot be fit into the free space (such a situation can occur if the package is too large for the free space), the next prereservation candidate in line will be served and so on.

Additionally, the partner can now specify the same attribute within the NextReservationTimes attribute indicating that if the first desired time could not be met, the next one will be considered (the earliest possible) without losing the prereservation priority in the hypothetical queue, thus ensuring the fairness of first come first served. However the number of elements within the NextReservationTimes attribute array is limited.

It is important to note that this PRERESERVATION works in conjunction with the classic reservation! You enable the PRERESERVATION behaviour by providing the prereservationExpirationDate attribute(s).

You can also combine the prereservationExpirationDate attribute(s) (see below).

Type of implementation

You may choose, which version of the algorithm you would like to use.

Without NextReservationTimes

You will supply only the root time slot with a deadline. This implementation is very straight forward and requires the least customization, since the callback doesn’t have to be extended by new attributes.

With NextReservationTimes

Additionaly you will supply time slots with deadlines within the NextReservationTimes attribute. This implementation requires more customization, however it is much more flexible and allows for the optimal behaviour by taking advantage of multiple time slots. This way if we can make a reservation with state RESERVED to any of your time slots, we will do so, however you still will be eligible for time slot change to an earlier one, if a space frees up! So no matter the status of the (pre)reservation (PRERESERVED or RESERVED) its time slot may change to the earlier you have supplied.

API Changes

Input attributes

In both cases, the value of the new prereservationExpirationDate attribute must not be in the past or after the value of the startReservationDate attribute.

Without NextReservationTimes

Under the reservation attributes a new attribute prereservationExpirationDate is available (see line 9)

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" ... //Additional attributes, such as packages etc. }, "relationships": { "box": { "id": 1 } } } } }

With NextReservationTimes

Prereservation behaviour only

Under the reservation attributes a new attribute prereservationExpirationDate is available (see lines 9 and 14)

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", }, ] ... //Additional attributes, such as packages etc. }, "relationships": { "box": { "id": 1 } } } } }

Prereservation + classic reservation behaviour

As stated above, it is not neccessary to supply the parameter for all the time slots (see the missing attribute between lines 8 and 9 and the supplied attribute on line 13):

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", }, ] ... //Additional attributes, such as packages etc. }, "relationships": { "box": { "id": 1 } } } } }

The behaviour here is that the first time slot behaves like a classic reservation (it tries to create a reservation). In case it failes, you shall receive a prereservation behaviour for the second supplied time slot (that means, we shall not try to change the reservation time slot to the first supplied in case a space is freed up).

Response

Structure of the response remains the same, however we add a new value for a status attribute PRERESERVED.

Also new optional attributes are available:

  • PrereservationExpirationDate,

  • NextReservationTimes.

You can check these out on API V2 Endpoints description page. These are optional, thus queriable via the parameter “fields[reservation]”.

Note, that the NextReservationTimes in response returns ALL time slots that we keep active for your reservation. Also, the core time slot is returned as well (which is defined by “root” time slot - startReservationDate, expirationDate and prereservationExpirationDate directly under the attributes).

Callbacks

Depending on the way you decide to implement the Prereservation, the callbacks may change in two ways.

Without NextReservationTimes

Not much changes, apart from your API has to accept callback with two new statuses

  • RESERVED

  • EXPIRED

Why? See a brief example below:
In case you use the Prereservation funcionality and the reservation cannot be created immediately a Prereservation is created.

  • If a space is freed up in the desired AlzaBox before the deadline specified by you (prereservationExpirationDate) then the reservation’s status is changed from PRERESERVED to RESERVED. Such a change will trigger the sending of the callback to your API with the status change toRESERVED.

  • If a space is not freed up in the desired AlzaBox before the deadline then the reservation’s status is changed to EXPIRED. Such a change will trigger the sending of the callback to your API with the status change to EXPIRED.

With NextReservationTimes

These new fields will need to be enabled for you in our configuration. If you choose to use this implementation, please let us know so that we can enable these fields for you.

These new fields are nullable strings. They may be null for cases when the time slot has not changed (basically standard callback for state changed).

Apart from the acceptance of the new statuses above, you will also have to support new status PRERESERVED. Additionaly you will have to support two new fields:

  • startReservationDate,

  • expirationDate.

The meaning and format is the same as in the input for POST reservation.

These new fields together with status field may indicate different behaviours, which you may ask to be disabled (see versions below)

It will be possible to change the time slot for those with status PRERESERVED but ALSO RESERVED (see the reservation examples). This means that if you we have successfully created a reservation for one of your later time slots and a space frees up in earlier time slot (that you have supplied) before the deadline, we will change yours reservation’s time slot to the earlier one.

The meaning and format is the same as in the input for POST reservation.

Related content