Sub-Hire & Procurement
Purchase orders, virtual stock intakes, sub-hire shortage resolution, cost apportionment, and supplier returns.
Overview
When owned stock cannot cover a shortage, sub-hire procures supply from suppliers. The loop connects shortage detection → purchase order → virtual stock intake → availability supply → cost apportionment → optional supplier return.
Event-sourced purchase orders and virtual stock intakes follow the same Verbs projection pattern as invoices and rentals.
| Area | Route |
|---|---|
| Purchase orders | /purchase-orders |
| Virtual stock intakes | /virtual-stock |
| Rental shortages | /rentals/{rental}/shortages |
Catalogue item suppliers
Catalogue items can carry supplier reference data — preferred supplier, unit cost, cost basis, SKU, lead time, and minimum order quantity. Manage on the catalogue item detail page and via POST /api/v1/catalogue_items/{catalogue_item}/suppliers/{id}/set_preferred.
Supplier costs inform PO line pricing and margin reporting; costs.view gates cost field visibility on POs and intakes (not whole resources).
Purchase orders
PO lifecycle:
| Status transition | Action |
|---|---|
| Draft | Create and edit lines |
| Record as sent | Change status to Sent and record the sent time; does not approve or contact the supplier |
| Receive | Record goods received; triggers intake workflow |
| Cancel | Cancel open PO |
PO tax uses the purchase axis (distinct from sales tax on invoices). See Purchase Orders API.
Draft edits recheck the committed purchase-order state before allocating new line IDs or event IDs. An edit that waited behind Record as sent keeps the existing 422 invalid_state refusal without changing stored rows or event-allocation cache. Omitting currency retains the committed purchase-order currency; supplier-cost lookup, expected tax and totals run after the owner lock, using the current inputs and source records.
Draft deletion rechecks the current purchase-order state under its owner lock before allocating an event ID. A purchase order sent during the wait keeps the existing 422 invalid_state refusal and leaves stored rows and event-allocation cache unchanged. A valid deletion preserves the committed draft facts and advances the aggregate version once.
Virtual stock intakes
Virtual stock intakes represent supplier stock entering your availability pool as signed supply — the availability engine treats confirmed intake quantity as available for allocation without adding owned stock.
Creation from a sub-hire purchase-order line locks the selected source order and its current line before deriving intake facts. A completed source edit supplies the current catalogue item, warehouse, rental, quantity, unit cost and currency, and the current catalogue item is checked under its catalogue lock. If the source becomes an ordinary purchase during the wait, creation keeps the existing 422 validation refusal without changing stored rows or event-allocation cache. A line that no longer belongs to the selected order keeps the existing purchase-order mismatch refusal. A source line removed during the wait keeps the existing 404 not_found response; both refusals occur before event or sequence allocation.
Draft edits recheck the committed intake state after acquiring its owner lock. An edit that waited behind cancellation keeps the existing 422 invalid_state refusal and leaves stored rows and event-allocation cache unchanged. Omitting currency_code retains the committed intake currency, including a currency change that completed during the wait; an explicit currency remains the new command's choice.
Draft deletion rechecks the current intake state under its owner lock before allocating an event ID. An intake cancelled during the wait keeps the existing 422 invalid_state refusal and leaves stored rows and event-allocation cache unchanged. A valid deletion preserves the committed draft facts and advances the aggregate version once.
Intake lifecycle:
| Action | Purpose |
|---|---|
| Confirm | Confirm intake terms |
| Receive | Record physical receipt |
| Apportion | Allocate cost across rentals |
| Return | Return stock to supplier |
| Cancel | Cancel intake |
See Virtual Stock Intakes API.
Sub-hire shortage resolver
The SubHireResolver is the seventh shortage resolution path (alongside the six non-PO resolvers documented in Shortages). It creates or consolidates purchase orders from shortage lines.
Batch consolidation groups shortages across rentals into a single PO where supplier and dates align.
Flow: PO receipt → intake confirm → shortage clear — receiving a PO creates or updates the intake, which feeds availability and clears the originating shortage.
Cost apportionment
When one intake serves multiple rentals, cost apportionment distributes supplier cost using one of five strategies through the cost event stream. Date changes on rentals trigger recalculation.
For date-sensitive strategies, the recalculation runs just after the date change is saved, as a separate step that locks every participating rental. If it fails, the date change is kept and the preceding split stays until the next trigger or a manual POST /api/v1/virtual_stock_intakes/{id}/apportion. The failure is logged as a virtual_stock.reapportion_failed warning; a failed follow-up step of any kind is also logged as verbs.after_commit_failed. A concurrent change to the participating rentals refuses an apportionment with the retryable code virtual_stock_cost_changed; the date-change recalculation retries it once.
The split always covers every participating rental, but the apportionment response lists only the rentals the caller can see; the allocations to the others are summed in hidden_allocated_total_minor. Inside a larger transaction (a sub-hire receiving scan, for example), confirming, receiving, cancelling or returning an intake apportions or removes its costs after that transaction commits; a failure is logged as virtual_stock.apportion_after_commit_failed.
Override apportioned cost per rental: PUT /api/v1/virtual_stock_intakes/{id}/cost_overrides and DELETE .../cost_overrides/{rental}.
Apportioning writes rental cost rows, so the apportion endpoint and the two cost override endpoints need the same authority: the virtual_stock.edit and costs.view permissions, access to the intake's warehouse, and the virtual_stock:write token ability. A token with only virtual_stock:read, or a user with only virtual_assets.view, gets 403.
Returns and P&L
Return-to-supplier workflow records stock leaving your pool. Intake P&L surfaces per-intake and per-rental profit impact when the viewer has cost visibility.
Barcoded virtual stock
Tracked sub-hire inventory can use barcoded virtual-stock assets — individual serial numbers on intake lines for scan-based fulfilment.
Using it in the app
Sub-hire UI spans catalogue item suppliers, shortage resolution, purchase orders, virtual stock, and read-only cost apportionment on rentals.
Navigation
| Screen | Route | Nav location | Gate |
|---|---|---|---|
| Suppliers | /catalogue-items/{catalogue_item}/suppliers |
Catalogue item tab | Tab visible with costs.view |
| Purchase Orders | /purchase-orders |
Finance mega-menu + Purchasing sidebar | purchase_orders.view |
| Virtual Stock | /virtual-stock |
Catalogue mega-menu + sidebar | virtual_assets.view |
| Rental Shortages | /rentals/{id}/shortages |
Rental tab | shortages.view + allocation visibility |
| Rental Costs | /rentals/{id}/costs |
Rental tab | rentals.view; amounts @costs |
Virtual Stock is labelled Sub-hire supply windows in the header mega-menu. Finance-only users (invoices.access without catalogue access) do not see Virtual Stock links.
Suppliers tab
On a catalogue item detail page, open Suppliers (tab requires costs.view and catalogue-items.view).
Table columns: Supplier, Basis, Cost, SKU, Lead Time, MOQ, Warehouse, Preferred
| Action | Permission |
|---|---|
| Add Supplier | catalogue-items.suppliers |
| Set preferred | catalogue-items.suppliers |
| Edit / Delete | catalogue-items.suppliers |
Without costs.view, the tab is hidden — not merely redacted.
Shortages tab — sub-hire resolution
Visible for Order state or Quote + Held. Tab badge shows unresolved shortage count.
Sub-hire option cards appear in Detected Shortages with resolver options sized to the shortfall. Cards can show Preferred (preferred supplier first), Partial, and Auto badges. Resolve across jobs offers batch consolidation into a single PO when supplier and dates align — Apply batch.
Lifecycle buttons on applied resolutions: Confirm, Start, Fulfill, Cancel, Fail.
Flow in UI: pick sub-hire option → draft PO created → receive PO → intake confirm → shortage clears (see PO and intake screens below).
Purchase orders
The draft form starts with Type, Supplier (company, warehouse and reference) and Line items. Expand More details for Notes, Supplier Notes and Total Weight.
Index (/purchase-orders) — Finance meta label; status chips; data table with live filters; columns Number, Type, Status, Supplier, Warehouse, Total, Expected; New Draft when purchase_orders.create.
Show page actions (all writes also require costs.view):
| Action | Permission | Notes |
|---|---|---|
| Edit | purchase_orders.edit |
Draft only |
| Record as sent | purchase_orders.send |
Changes status and sent time only; no approval or supplier transmission |
| Receive | purchase_orders.receive |
The UI modal submits a positive quantity for every outstanding line; use the API to omit undelivered lines |
| Cancel | purchase_orders.cancel |
Open PO |
| Delete | purchase_orders.delete |
Draft only |
For sub_hire PO lines, Create intake links pre-fill /virtual-stock/create?purchase_order_id=…&purchase_order_item_id=… with supplier unit costs from the PO line.
The purchase-order show page (/purchase-orders/{purchaseOrder}) has an identity band, headline cards that drill ?register=recon|alloc|life, a signed-variance bar on reconciliation, four briefing verdicts, line items and their totals (for cost readers) in the main column, and one supplier sidebar. Open Receiving → Reconciliation, Receiving → Virtual stock intakes (sub-hire orders), More → Details or More → History for the supporting pages. Documents is a direct link when it is the only visible page in its group; Activities is under More. Plugins can add further tabs. Sent POs keep the line editor read-only.
The PO supplier picker searches every Company account rather than a supplier-configured subset. The receive action supports partial quantities, but the show-page modal includes every outstanding line and rejects zero; a delivery that skips an outstanding line must be recorded through the receive API with only the delivered lines, or held outside Signals until an accurate workflow is available.
Documents card on the PO show page lists purchase-order document projections (header/body/footer snapshot) with document number, type, created time, and a Download PDF link. Empty state: "No documents."
Receiving → Virtual stock intakes (/purchase-orders/{purchaseOrder}/intakes) lists linked intakes with Return to supplier when applicable.
Virtual stock intakes
The new intake form groups Catalogue item, Stock (warehouse and quantity), Availability window and Cost. Expand More details for Notes.
Index — status chips; columns Number, Catalogue item, Warehouse, Status, Window, Qty, Total Cost (when costs.view); New Intake.
Show page:
| Action | Permission |
|---|---|
| Confirm | virtual_stock.confirm |
| Receive | virtual_stock.receive (partial/over-receipt handled in receive modal) |
| Return to supplier | virtual_stock.return |
| Cancel / Delete | Draft only |
Overview shows virtual assets in the main column and one intake facts sidebar, including notes. Related opens the linked purchase order or catalogue item when permitted. Cost apportionment & P&L opens /virtual-stock/{id}/profit-and-loss for users with costs.view; as the only Finance page it appears as a direct link.
Late return appears as an amber badge on the intake show page when the intake window has passed without return.
Rental Costs tab
Read-only table: Description, Cost Type, Transaction Type, Amount (@costs), Qty, Optional. Lines linked to an intake show a Intake {number} link to /virtual-stock/{id} when the viewer has cost visibility.
Manual cost overrides and apportionment editing are API-driven — the Costs tab does not expose override controls.
Permissions summary
| Permission | UI effect |
|---|---|
costs.view |
Suppliers tab, PO/virtual-stock writes, cost columns |
catalogue-items.suppliers |
Create, edit and delete catalogue item suppliers |
shortages.view / shortages.resolve |
Shortages tab view / resolution buttons |
purchase_orders.* |
PO list and lifecycle actions |
virtual_stock.* |
Intake list and lifecycle actions |
Related documentation
- Shortages — detection, gate, and resolver panel
- Equipment Availability — signed supply in availability calculations
- Tax & Compliance — purchase-axis tax
- Purchase Orders API
- Virtual Stock Intakes API