Spare Item Allocations

A spare item allocation defines the minimum and/or maximum quantity of a specific item type and variant that a spares pool is expected to hold. Allocations are advisory: They describe target stock levels so that low-stock and excess-stock conditions can be surfaced in the UI and queried via the API. They are not enforced against the spare items actually present in the pool, and carry no direct relationship to them.

A pool may hold at most one allocation per unique combination of item type, item ID, and variant.

Fields

Pool

The spares pool to which this allocation applies.

Item Type

The content type of the referenced item. One of rack type, device type, module type, or cable type.

Item ID

The primary key of the referenced item within its type.

Variant

An optional JSON object of attributes that distinguish this item from others of the same type. The tracked attributes match those used on spare items and BOM line items: airflow direction for devices and modules; color, length, and length unit for cables; racks have no variant attributes.

Minimum Quantity

The lower threshold for the item within the pool. Used to flag a low-stock condition - for example, to trigger a reorder or rebalance when stock at a site drops below a safe level. Defaults to 1, and may be cleared if only a maximum is being tracked.

Maximum Quantity

The upper threshold for the item within the pool. This is not a hard cap; it is used to identify pools holding excess stock that could be redistributed to other locations rather than purchasing more. Optional.

At least one of minimum quantity or maximum quantity must be specified, and the maximum (when set) may not be less than the minimum.

Fulfillment

An allocation reports the current quantity of conforming stock held in its pool: the total quantity of spare items in the same pool that share the allocation's item type and variant and are in the Serviceable status. This is computed on demand and is not stored.

An allocation is considered fulfilled when its current quantity is at least its minimum quantity (if set) and no greater than its maximum quantity (if set). Allocations that fall below their minimum or exceed their maximum are surfaced on the parent spares pool's detail page under a Threshold Violations panel, and the current on-hand quantity is shown alongside the thresholds in the pool's Allocations tab.

The computed stock state is also returned by the REST API as the read-only current_quantity, below_minimum, above_maximum, and is_fulfilled fields, so consumers do not need to reproduce the serviceable-stock aggregation themselves.