Reservations

The reservation is an action that guarantees supply allotment to a demand for later consumption.

The process of order conversion is a complex process as the seller must guarantee the quantity on an e-commerce site or store location are to be fulfilled at the end of the pipeline. Typically, if there is an order conversion delay between the front end and the backend system, it can lead to overselling if not handled properly. For example, on a product detail page, the seller can indicate the total quantity available and when two shoppers are adding the item to cart or checkout at the same time, there is a need for a deterministic way to resolve who receives the last quantity of the product.

The reservation enables item quantities to be set aside for short-time that enables backend system to complete the processing of demands. The reservation requests occur in real-time and have a nonlocking behavior such that when a request is received, the availability is verified before reservation booking. In case if the are multiple reservations to access the same quantity, the first successful booking is processed and all reservations that are done on later dates are rollback and rejected. The reservation quantity accepted is next considered in future availability lookups that includes the new reservation requests.

Following are the characteristics of inventory reservation requests:
  • Auto rollback on unsuccessful reservation
  • Reservation expiry is configurable
  • Reservation is consumable as part of demand update.
  • Reservation can be grouped by reference
  • Partial reservation is supported
You can use reservations for the following:

Creating reservation for node or network

You can create reservations at the node and network level.
Reservation at node level
Creating a node level reservation enables inventory to be blocked at a specific shipping location or node. You can create reservation of one or more items at the specified quantity. On success, a reservation confirmation ID is returned.
Note: Partial reservation is supported in case of node-level reservation.

A successful reservation considers a type of demand that impacts the inventory availability. All reservation has an expiration period and at the end of the period, the inventory is returned to the available pool if not consumed via an order capture.

Reservation at network level
To maximize the order capture capability, a fulfillment manager setup a network of shipping locations. The network reservation is typically use on an e-commerce system as at the time of capture it is unknown which shipping location is used for fulfillment.
Capturing a network reservation affects the inventory level at both network and node level. Consider there are two nodes each with 5 quantity availability then there would be 10 qty total availability for reservation.
Note: When a network reservation is created, the reservation automatically breaks into node level reservation based on the node priority.

For more information, see Reservations by using node priority behavior.

Note: The Availability logic considers supplies, demands and active reservations among other things to calculate the actual availability.
For more information about special cases in reservation, see Special cases.
For more information about retrieving the list of active reservations, see Get Reservations API.

In both cases of node or network reservation, you can use the capability of customizing reservation ID. For more information, see Creating reservations with custom reservation ID.

Reservations by using node priority behavior

When a network level reservation is created, the system considers the network availability before blocking inventory quantity. In some complex scenario where one or more nodes is part of multiple networks, this can quickly lead to an overselling scenario.

For example, consider Node1 has 5 qty and Node2 has 7 qty of availability. If two distribution groups are created as DG1 and DG2 where both have the same node, then both observe the same availability of 12 qty. In this legacy behavior, the reservation created against one distribution group is not aware of the other group. This means that it is possible for both DG1 and DG2 to reserve 12 qty leading to overselling.

To overcome this behavior, the seller is required to track these network level reservations as uncommitted reservations and convert them into node level reservation to mitigate the overselling risk. The node priority reservation for distribution group is introduced in reservation logic to minimize the seller effort in performing the network to node reservation conversion.

The fundamental difference with node priority reservation is that the system performs an inventory check on both individual node in the distribution group and network upon accepting the requested quantity. The reservation quantity is assigned to a node instead of network level so that any network sharing the same node has the latest inventory picture. When multiple nodes exist in the distribution group definition, the reservation booking is done in the order of the node priority value.

To configure the order which nodes are considered, the user can defined the priority value for each node in the distribution group as multiple nodes can have the same priority value. The tie breaker is the node with the oldest inventory is reserved first.
For more information, see Distribution Group API.

As an example, DG1 has [Node2, Node1, Node3, Node4] as the node priority sequence. This means Node2 availability is always reserved first. Once the Node2 depletes, the system then traverses to subsequent priority node until the reservation request quantity is met.

Updating reservation quantity

On an existing reservation, you can perform the following actions:
  • Increasing and decreasing a reservation quantity for a reservation line.
    Note: In the case of quantity change, the reservation supports partial reservation quantity increase. This is true until the inventory is available at the specific item-node combination.
  • Updating expiration time.
Note: Set the acceptPartialReserve flag to true for allowing the order line to release for any reserved quantity that is absolute reservation. In case the flag is set to false, the order lines are processed when the whole quantity is reserved.

Defining expiration times for reservations

When you create a reservation for a node or network, you can define the expiry timestamp at the individual reservation line level or for all the reservations with the same reference. When a reservation expires, the reserved quantity is released back into the availability pool. At that point, the availability APIs reflect the updated inventory and relevant events may be published if subscriptions are in place. The events includes productAvailbaility, dgAvailability, supplyAvailbility events. For more information, see Event formats.

Extending reservations for a cart or by reference

The existing reservation can be overridden with the new expiry timestamp during reservation creation or update. For example, if you set the flag with an overriding expiry timestamp defined, the reservation reference consists of [rsv1, rsv2, rsv3] that updates the expiry for all the reservations. If you do not specify the overriding expiryTs in the request input, the flag can be ignored.
Note:
  • The system enforces the reservation limit for the maximum of 30 days with a default value of 15 minutes.
  • You can extend the expiration time for multiple reservations at once that have the same reference.
For more information, see Update Reservations API.

Searching inventory reservations

Search inventory reservation allows you to search for reservations by item, reference or reservation ID. You can also search the inventory reservations with the help of the Search Reservations API.

For more information on steps to search inventory reservations, see Searching the inventory reservations by Reference or Reservation ID.

Removing reservations

You can delete or use the selected reservation as a part of demand update when an order gets converted.

The system performs a validation to avoid duplication of reservation ID in the reservation API call. The successful reservation creation returns the corresponding reference value from the response payload. The APIs that work with the custom reservation ID are as follows:
  • GET
  • DELETE
  • POST
  • PATCH
For more information about removing the reservations, see Delete Reservations API.

Reservation status

The following are the reservation types that can be made against specific node, specific distribution group, and specific delivery method depending on shipment or pickup.

Consider an online shopping scenario where a shopper wants to place an order for an item. When the item is added to a cart or as part of checkout, the following steps occur in the backend system:
  1. Obtain the item availability and compare it against the request quantity.
  2. If sufficient quantity is available, an item reservation is requested.
    Note: The second step can be performed when the items are added to a cart or can be done when items are in process of checkout.
  3. Verify the reservation state and determine whether the reservation is fully reserved, partial reserved, or unreserved. If the quantity is not fully reserved, the user should be notified of insufficient quantity.
  4. If the quantity is canceled or removed from the cart, the corresponding reservation should be amended to reflect the latest quantity reserved that frees up the availability to other shoppers.
  5. The reservation is converted into order or demand. The backend system includes the reservation ID as part of demand and order update, which triggers consumption of the reservation.
When the inventory is low, the reservation can have one of the following outcomes:
Reservation Outcome
Reserved If the full quantity is reserved, the store publishes a demand that includes the reservation details so that the reservation can be consumed.
Partially reserved The partial quantities are reserved on the system. Based on the order acceptance status, the customer needs to determine whether the reservation needs to be preserved or deleted.
Unreserved The inventory is not reserved and the customers need to look for alternative inventory.