Shortages
Detect inventory shortfalls on a rental, gate conversion with Block/Warn/Allow, and record honest resolution plans including transfers and sub-hire.
Overview
A shortage is the gap between what a rental's line items need and what the availability engine reports as free for those catalogue items, at that warehouse, over those dates. The Shortages tab on a rental surfaces every short line, gates the conversion to an order according to your policy, and gives you a set of resolvers to close the gap.
Shortages are computed, never stored — they are recalculated live every time the tab is read, and change as other bookings, returns, stock movements, and resolutions happen. Only the resolutions and acknowledgements you record are persisted.
Route: /rentals/{id}/shortages
Reading shortages requires the shortages.view permission; applying and transitioning resolutions requires shortages.resolve. Users without the resolve permission see the panel read-only.
How Shortages Are Detected
For each line item, the engine compares the requested quantity against the available quantity for the catalogue item, warehouse, and the line's dates. Where requested exceeds available, the line is short. The panel shows, per short line, the requested and available quantities, the shortfall (the gross gap), and the remaining shortfall (the gap after netting off any active resolutions — the figure the resolvers act on).
A shortage on a confirmed order is treated as critical; the same gap on a quote is informational until you commit.
The Confirmation Gate
When you Confirm order, the warehouse's shortage policy decides whether unresolved shortages may pass:
| Policy | Behaviour |
|---|---|
| Block | Conversion is rejected while unresolved shortages exist. You must resolve or reduce them first. |
| Warn | Conversion proceeds, but an acknowledgement is recorded. |
| Allow | Conversion proceeds freely; shortages stay visible but never gate it. |
The Shortages tab shows the gate's current decision ahead of time, so you know before you click Confirm order whether the job will be blocked, warned, or allowed.
Overriding the gate
A user with the shortages.ignore permission relaxes the gate one level for themselves — Block becomes Warn, and Warn becomes Allow — so a senior operator can knowingly push a short order through. The shortages stay visible either way; only the hard block is lifted.
Owners receive the same relaxation implicitly: the owner all-access hook grants every permission (including shortages.ignore), so a Block policy never hard-blocks an owner — conversion proceeds with an acknowledgement recorded, same as an explicit override. This is intentional. Making Block absolute for all actors, owners included, would require a dedicated setting (e.g. shortage_block_is_absolute); that setting is not currently enabled.
Note
Proceeding past a warning records a shortage acknowledgement with a frozen snapshot of what the shortage looked like and who confirmed it — the audit trail for a short order. You can also acknowledge shortages explicitly from the tab ahead of conversion using the Acknowledge action, which captures an optional note.
The Dispatch Policy
Alongside the conversion gate, each warehouse carries a dispatch policy governing whether short equipment may be physically booked out at fulfilment time. The panel surfaces the warehouse's dispatch policy so the operator dispatching the order knows whether a remaining shortfall will block the book-out.
The Resolvers
For each short line, the panel lists the resolvers that apply, each offering one or more concrete options. Seven built-in resolvers ship with the platform, ordered by display priority:
| Resolver | When it applies / what it does |
|---|---|
| Reallocate | Record a pending intent to release stock held by an overlapping unconfirmed quote. It does not release that quote's stock. |
| Substitute | Dormant: no catalogue-item substitution data source exists, so this resolver produces no options and the panel states that substitution is unavailable. |
| Transfer | Bring stock in from another warehouse that has it free. |
| Date shift | Record a confirmed proposal for a window where the item is available. It does not edit the rental dates. |
| Partial | Record a confirmed partial-fulfilment decision (for example "fulfil 4 of 6"). It does not reduce the rental line quantity. |
| Waitlist | Record the shortfall and monitor availability, so the line can be filled if stock frees up. |
| Sub-hire | Create or consolidate purchase orders from shortage lines — procures virtual stock from suppliers. See Sub-Hire & Procurement. |
Partial and Date shift immediately record a confirmed decision or proposal, but leave the rental line and dates unchanged. Waitlist records a monitoring resolution. Reallocate records pending intent only; Transfer and Sub-hire create downstream draft records and also require follow-up. Substitute remains dormant until a data source exists.
To plan a resolution, choose Review, optionally add a note, and choose Record resolution. The shortage is recomputed before the record is created, and active resolution quantities reduce the panel's Remaining figure. That accounting does not prove the stock, dates, or line quantity have actually changed; complete the named downstream workflow and recheck live availability.
The Resolution Lifecycle
A persisted resolution moves through a defined lifecycle, and the panel only offers the transitions that are legal from a resolution's current state:
| Transition | Meaning |
|---|---|
| Confirm | Lock in a pending resolution as the agreed plan. |
| Start | Mark the resolution as in progress (for example the transfer is on its way). |
| Fulfill | Complete the resolution — the stock is now in hand. |
| Cancel | Abandon the resolution (captures an optional reason). |
| Fail | Record that the resolution could not be completed (captures an optional reason). |
Cancel and fail capture a reason in a short modal; the others are single-click. An illegal transition (one not permitted from the current state) is rejected with a clear message rather than an error, so a raced or stale click never breaks the panel.
Shortage Resolution API
The REST surface matches the panel and uses the shortages:read ability for
discovery and shortages:write for mutations. Batch discovery recomputes live
shortfalls and groups only supported catalogue-item/warehouse lines; mutation
responses return the persisted resolution and whether downstream follow-up is
still required.
| Route name | Method and path | Purpose |
|---|---|---|
api.v1.shortage_resolutions.store |
POST /api/v1/shortage_resolutions |
Apply one resolver option to a current line-item shortage. |
api.v1.shortage_resolutions.batch.index |
GET /api/v1/shortage_resolutions/batch |
List supported batch groups and resolver options for rental_line_ids[]. |
api.v1.shortage_resolutions.batch.store |
POST /api/v1/shortage_resolutions/batch |
Apply one resolver option across a supported group. |
api.v1.shortage_resolutions.transition |
POST /api/v1/shortage_resolutions/{resolution}/transition |
Apply an explicit target status through the lifecycle matrix. |
api.v1.shortage_resolutions.confirm |
PATCH /api/v1/shortage_resolutions/{resolution}/confirm |
Confirm a pending or monitoring plan. |
api.v1.shortage_resolutions.start |
PATCH /api/v1/shortage_resolutions/{resolution}/start |
Start fulfilment of a confirmed plan. |
api.v1.shortage_resolutions.fulfill |
PATCH /api/v1/shortage_resolutions/{resolution}/fulfill |
Mark active fulfilment complete. |
api.v1.shortage_resolutions.cancel |
PATCH /api/v1/shortage_resolutions/{resolution}/cancel |
Cancel an unstarted plan with an optional reason. |
api.v1.shortage_resolutions.fail |
PATCH /api/v1/shortage_resolutions/{resolution}/fail |
Record that a pending or monitoring plan failed. |
All lifecycle writes recheck the current status. A stale or illegal transition
returns 422 and does not append an event or alter the resolution.
Live Updates
The Shortages tab is live. It subscribes to the rental's availability broadcast, so when the shortage picture changes — because of a booking, return, stock movement, or a resolution applied elsewhere — the panel re-reads the engine and refreshes the short lines, resolver options, gate decision, and resolution list without a manual reload.
Related
- Shortages API — the REST endpoints for detecting and resolving shortages.
- Rentals — where shortages arise and where Confirm order is gated.
- Equipment Availability — spotting shortages across the wider plan.