Last updated

Listing stock management

Reference documentation for listing stock management.

Table of Contents

The listing stock management features of Flex allow providers to define the quantity of available stock for purchase. There are three key concepts related to stock management:

  • stock represents the quantity of available units, associated with a listing. The units can be anything that makes sense for a given listing or marketplace concept, as long as the quantity is integer number. For instance - the number of physical items kept in inventory; a number of virtual items; number of available batches, when a listing is sold in batches rather than as individual items, etc.
  • A stock adjustment is a record of change in the quantity of stock for a listing. A positive adjustment represents an increase in available stock, while a negative adjustment represents a decrease. For instance, providers add stock by recording a positive stock adjustment, while sales that happen through are transaction are recorded as negative adjustments. Stock adjustments are immutable.
  • A stock reservation represents a reservation or purchase of particular quantity of stock through a transaction.

Providers and operators can manage stock for listings through the Marketplace API and the Integration API. Stock adjustments can be created either directly, or through a "compare and set" operation that sets the total available stock consistently, given an expected current total stock quantity for a listing.

All stock reservations are created through transactions, governed by your transaction process. An appropriately constructed transaction process ensures that reservations can only be placed for available quantities of stock.

Stock reservation states

A stock reservation can be in one of several possible states: pending, proposed, accepted, cancelled or declined. Just as with bookings, stock reservations change state only through a corresponding transaction transition, using one of the stock reservation actions.

All stock reservations in pending or accepted states count as reservation against the listing's available stock. On the other hand, stock reservations in the proposed, cancelled or declined states do not affect the current available stock.

It is important to note that the stock reservation's effect on stock is explicitly recorded as individual stock adjustments as the reservation progresses through its states. For example, if a proposed reservation is accepted, a new stock adjustment with negative sign (decrease of stock) is recorded. Similarly, if an accepted stock reservation changes state to cancelled, a positive stock adjustment (increase of stock) is recorded. On the other hand, a new stock adjustment is not recorded when the change of states does not require one, as is the case for change from pending to accepted state. All this ensures that the set of stock adjustments for a particular listing represents an accurate and detailed view of how the listing's available stock has changed over time.

The figure below illustrates the possible stock reservation states, transitions between the states and the corresponding actions that you can use in your transaction process.

Stock reservation states

Negative stock quantity

Generally, the total available stock of a listing cannot be a negative number. However, in some rare cases, it is possible that the total stock becomes negative. This should be considered an error case and is an indication that at least some transaction transition failed to execute properly. Such a transaction transition would include some of the actions that release some reserved stock (such as :action/decline-stock-reservation or :action/cancel-stock-reservation), which would typically be present in a transition representing a cancellation or a refund. As a mitigation, it is recommended to always place actions that release a stock reservation last in the sequence of actions of a transition.

Further reading