SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

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.

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