Reservations

What you can build

The central action on a work: the patron reserves, chooses where to pick up, and sees their place in the queue straight away. Fees and limits come from the library system, so the client can show them before the patron confirms.

Typical flow

1. The patron chooses a publication. The client reads its reserveId from GetHoldings.
2. The client reads the patron's fee, limits and pick-up locations from GetPatronConfiguration.
3. The patron chooses where to pick up (2.5.8).
4. The client creates the reservation with CreatePatronReservation.
5. The response is the reservation, including the patron's queueNumber when it is known.

What the API provides

• A publication without a reserveId cannot be reserved.
• A reservation fee has chargedAt: reservation (charged when the hold is placed) or checkout (charged at pick-up). amount is in minor units, currency in ISO 4217.
• Reservation limits come as daily and max.

What you can build

An overview of everything the patron has reserved: what is ready to pick up, what is in the queue, and what is paused.

Typical flow

1. The client fetches the reservations with GetPatronReservations.
2. Each reservation is shown with its state and, when known, its place in the queue.

What the API provides

• state is ready_for_pickup, in_queue or postponed.
• queueNumber 1 means first in line. When the field is missing, the position is unknown.
• fulfillmentBy tells how the reservation is fulfilled: local_circulation, interlibrary_loan, purchase or unknown.

What you can build

Patrons cancel a reservation themselves, without contacting the library.

Typical flow

1. The patron chooses a reservation and confirms the cancellation.
2. The client calls DeletePatronReservation.

Typical flow

1. The client lists the pick-up locations with GetLocations.
2. The patron chooses a new one.
3. The client updates the reservation with UpdatePatronReservation.

What the API provides

• UpdatePatronReservation changes only pickupLocation.

What you can build

Paused reservations stay in the patron's overview, marked as paused.

Typical flow

1. The patron chooses a period.
2. The client sets reservation.postpone with UpdatePatronInformation.
3. Reservations in the period show the state postponed.

What the API provides

• The pause applies to the patron, not to a single reservation.
• The period may be open at one end, for example from today with no end date.

Typical flow

1. The client reads the patron's default pick-up location from GetPatronInformation (pickupLocation).
2. The patron can choose another one from the list.
3. The chosen location is sent as pickupLocation with CreatePatronReservation.

What the API provides

• The options come from, in order of precedence: the item's pickupLocations in GetHoldings, the holding's pickupLocations, the patron's configuration (GetPatronConfiguration) and GetLocations.
• Each level replaces the ones below it entirely. If no level defines any pick-up locations, the material cannot be reserved.

Typical flow

1. Staff identify the patron.
2. The reservation is created with CreatePatronReservation for that patron.

What the API provides

• The specification has no separate operation for staff and describes no way to act on a patron's behalf.