Create, update, and query rental quotes and orders through the rentals API.

Rentals API

CRUD and lifecycle endpoints for rentals — the event-sourced quote/order documents that drive the rental lifecycle.

Rentals use a two-axis model: a state (Enquiry, Quote, Order) and a per-state status (e.g. Quote/Reserved, Order/On Hire). Reads hit a read-optimised projection; every write is recorded as an event so full history is preserved.

Endpoints#

Authentication#

Requires a Sanctum bearer token with rentals:read (GET) or rentals:write (POST/PUT/DELETE) ability, alongside the matching rentals.view / rentals.create / rentals.edit / rentals.delete permission.

Rental Field Reference#

All rental responses include the following fields under the rental key.

Identity & Header#

State & Status#

Dates#

Fulfilment Flags#

Delivery & Collection Addresses#

Include delivery_address and collection_address via ?include=delivery_address,collection_address to embed the full address object (street, city, postcode, country, etc.).

Pricing & Totals#

All money values are returned as decimal strings (e.g. "125.50").

Quote Version Summary#

Lazy Includes#

These fields are null unless the relationship is eager-loaded via ?include=:

Response Meta Block#

Every show/write response includes a top-level meta block alongside rental:

{
    "rental": { ... },
    "meta": {
        "can_edit": true,
        "can_destroy": false
    }
}

Two-Axis State Model#

Each response includes both the raw compatibility integer codes (state, status) and human-readable labels (state_label, status_label), plus the availability_phase the current status places on the availability engine.

List Rentals#

GET /api/v1/rentals

Returns rentals under the rentals key with a meta block (total, per_page, page).

Filters#

Ransack-compatible q[field_predicate]=value parameters:

Includes#

Eager-load relationships with ?include=account,venue,warehouse,owner,items,items.assets,costs,versions,versions.items.

The rental's custom_fields object is populated from the customFieldValues relation, which is eager-loaded by default — custom_fields is always present ({} when none are set), with no need to request it explicitly.

Live filters#

Apply a saved view with ?filter_id=42. The view's columns project a sparse response (only those fields plus id); custom-field columns (cf.*) filter the custom_fields object. Explicit q filters take priority over the view's filters. See Live filters API for details.

Sort#

sort=created_at, sort=-starts_at, sort=title, sort=charge_total, sort=state, sort=status (prefix with - for descending).

Pagination#

Offset-based: ?page=2&per_page=20 (max per_page 100).

Show Rental#

GET /api/v1/rentals/{id}

Returns the rental under the rental key. Supports ?include=.

The rental body also exposes the version summary fields active_version_id, version_count, and has_alternatives, the tag_list array, and (when included) a versions collection — so the Show page can sideload the quote versions in one call with ?include=versions,versions.items.

Rental Assets#

GET /api/v1/rentals/{id}/assets

A flat, paginated list of every per-asset assignment across all of the rental's line items (the rental_item_assets rows), returned under the assets key with a meta block. Use this for the Show page's assets tab without loading the full items payload. Each row matches the asset shape used elsewhere (id, rental_item_id, asset_id, status + status_label, lifecycle timestamps).

Requires rentals.view / rentals:read.

Filters#

Ransack-compatible q[field_predicate]=value:

Sort#

sort=status, sort=-dispatched_at, sort=allocated_at, sort=created_at (prefix with - for descending). Defaults to oldest-first.

Rental Availability#

GET /api/v1/rentals/{id}/availability

Returns the per-line availability picture under the availability key: for each catalogue-item-backed line, how many units are free over the line's own window at its own warehouse with the line's own demand excluded, plus its shortage shortfall. Lines that reference no catalogue item (services, ad-hoc lines) are omitted. Computed live from demands (no snapshot dependency), so it always reflects current state.

Each entry: rental_item_id, catalogue_item_id, warehouse_id, requested_quantity, available_for_item, shortage_quantity, has_shortage, from, to.

Requires rentals.view / rentals:read.

Rental Activity#

GET /api/v1/rentals/{id}/activity

A paginated, newest-first read of the audit trail (action_logs) scoped to this rental, returned under the activity key with a meta block. Saves the caller from knowing the underlying model FQCN that the global /api/v1/actions endpoint filters on. Each entry matches the action-log shape (action, user_id, user_name, old_values, new_values, ip_address, created_at).

Gated like the global action-log endpoint: requires action-log.view / action-log:read.

Create Rental#

POST /api/v1/rentals

Creates the rental as a Enquiry / Unconfirmed. A zero-padded compatibility number (e.g. "0000000042") is auto-generated from a per-warehouse running sequence and returned in the response. Money is supplied as a decimal string or minor-unit integer and returned as a decimal string.

Identity & Header#

Hire & Charge Dates#

Event Logistics Dates#

All fields are optional ISO 8601 date strings. Each phase is a _starts_at / _ends_at pair.

Fulfilment Flags#

Delivery & Collection#

Returns 201 with the created rental under the rental key.

Update Rental#

PUT /api/v1/rentals/{id}

Partial update of editable header fields. All fields are optional — omitted fields are left unchanged. A closed/terminal rental (Complete, Cancelled, Lost, Dead) cannot be edited and yields a 422.

For nullable clearable fields (venue_id, reference, description, external_description, delivery_instructions, collection_instructions, delivery_address_id, collection_address_id, chargeable_days, rating, tag_list) an explicit null clears the value; omitting the key entirely leaves it unchanged.

Identity & Header#

Hire & Charge Dates#

Event Logistics Dates#

All fields are optional ISO 8601 date strings. Providing a value sets or moves the date; omitting the key leaves it unchanged. Dates in this group are not clearable via null — use the Create path or contact the warehouse's team if a date must be removed.

Fulfilment Flags#

Delivery & Collection#

Delete Rental#

DELETE /api/v1/rentals/{id}

Soft-deletes the rental. The deletion is recorded as an event so history is preserved; the row drops out of list and availability reads. Returns 204.

Convert to Quote#

POST /api/v1/rentals/{id}/convert_to_quote

Transitions a Enquiry rental to a Quote / Provisional. Returns the updated rental under the rental key. An invalid transition (not currently an Enquiry) yields a 422.

Convert to Order#

POST /api/v1/rentals/{id}/convert_to_order

Transitions a Quote rental to an Order / Active. Returns the updated rental. An invalid transition yields a 422.

Change Status#

POST /api/v1/rentals/{id}/change_status

Moves the rental to a different status within its current state.

Returns the updated rental under the rental key.

Error Cases#

Available Actions#

GET /api/v1/rentals/{id}/available_actions

Returns the set of legal lifecycle actions for the current state/status combination, resolving each action's feasibility given the current state, the actor's permissions, and system checks (shortage gate, lock state, dispatch state). The UI uses this to show/hide action buttons without needing to reproduce the guard logic.

Requires rentals.view / rentals:read.

Response#

{
    "available_actions": [
        {
            "action": "convert_to_order",
            "label": "Convert to Order",
            "available": true,
            "disabled": false,
            "reason": null,
            "reason_code": null
        },
        {
            "action": "revert_to_enquiry",
            "label": "Revert to Enquiry",
            "available": false,
            "disabled": true,
            "reason": "Only an open, provisional quotation can be reverted to a draft.",
            "reason_code": "invalid_state"
        }
    ]
}

Each entry has action (the endpoint slug), label, available (boolean — the actor has permission and the state allows it), disabled, reason (human-readable explanation when not available), and reason_code (machine-readable, e.g. invalid_state, nothing_to_unlock, dispatched, permission).

Restore Rental#

POST /api/v1/rentals/{id}/restore

Restores a soft-deleted rental. The {id} must identify a soft-deleted record (use trashed=true on the list or the Delete/Restore flow from the UI). Returns the restored rental under the rental key (200 OK).

Requires rentals.delete / rentals:write.

Clone Rental#

POST /api/v1/rentals/{id}/clone

Creates a copy of the rental as a new Enquiry, including its line items, costs, and custom fields. The clone gets a fresh zero-padded rental number and is otherwise independent of the source; its source_rental_id points back to the original. Returns the new rental under the rental key (201 Created).

Requires rentals.create / rentals:write.

Reinstate#

POST /api/v1/rentals/{id}/reinstate

Reinstates a Lost, Dead, Postponed, or Cancelled rental back to its default open status (Quote/Provisional or Order/Active). Returns the updated rental. A 422 is returned for any other state/status.

Requires rentals.edit / rentals:write.

Revert to Quote#

POST /api/v1/rentals/{id}/revert_to_quote

Reverts an open Order (Active) back to a Quote / Provisional. The rental must not have any dispatched assets — if assets have been dispatched, the transition is rejected (422) until they are returned and all quantity demand is unwound.

Requires rentals.edit / rentals:write.

Revert to Enquiry#

POST /api/v1/rentals/{id}/revert_to_enquiry

Reverts an open, provisional Quote back to a Enquiry / Unconfirmed. Only allowed while the quotation is in the Provisional (open) status — a Reserved or closed quotation cannot be reverted. Returns the updated rental.

Requires rentals.edit / rentals:write.

Reopen#

POST /api/v1/rentals/{id}/reopen

Re-opens a Completed order back to Order / Active. Complete is the only terminal order status that can be re-opened (Cancelled orders use reinstate). Returns the updated rental.

Requires rentals.edit / rentals:write.

Unlock Locks#

POST /api/v1/rentals/{id}/unlock_locks

Releases any FX rate lock and/or tax lock currently in place on an order. Once unlocked, the next write (line edit, cost add, deal-price change) will re-snapshot the current exchange rates and tax rules. Returns the updated rental.

Requires the rentals.unlock_rates permission and rentals:write ability. Returns 422 when neither lock is set.

Lock Rates#

POST /api/v1/rentals/{id}/lock_locks

Applies FX and tax locks on a rental — snapshots the current exchange rate and freezes the tax treatment so later writes re-price the agreed net basis at the frozen rate rather than re-deriving FX/tax. This is the inverse of unlock_locks.

Requires the rentals.unlock_rates permission and rentals:write ability. Returns 422 when locks are already active. Returns the updated rental.

Restructure Items Tree#

PATCH /api/v1/rentals/{id}/items/tree

Reorders and/or re-nests the line-item tree in one operation. The body carries the full item set in display pre-order (top-to-bottom), each node carrying its target tree depth; the server rebuilds every item's materialised path from order + depth.

Requires rentals.edit / rentals:write. Returns the updated rental.

Rental Involved contacts#

Involved contacts are accounts (contacts or staff) attached to a rental in a named role — for example, a site contact, a crew chief, or an on-site supervisor. They are compatibility aliases (involved_contacts[] in the field set) and returned via ?include=involved_contacts.

List (via include)#

GET /api/v1/rentals/{id}?include=involved_contacts

Involved contacts are returned in the involved_contacts array on the rental. Each entry:

Add Involved contact#

POST /api/v1/rentals/{id}/involved_contacts

Returns the new involved_contact under the involved_contact key (201 Created).

Requires rentals.edit / rentals:write.

Update Involved contact#

PATCH /api/v1/rentals/{id}/involved_contacts/{involved_contact}

Returns the updated involved_contact under the involved_contact key. The {involved_contact} must belong to the rental (404 otherwise).

Remove Involved contact#

DELETE /api/v1/rentals/{id}/involved_contacts/{involved_contact}

Removes the involved_contact. Returns 204 No Content. The {involved_contact} must belong to the rental.

Rental Items#

Line items are the priced rows of a rental. Every write below flows through the event-sourced lifecycle: the rate engine resolves the per-unit price and duration-aware subtotal, the line discount is applied to the net (before tax), and the tax engine computes line-level tax. The rental's totals (charge_excluding_tax_total, tax_total, charge_including_tax_total, the per-type rental/sale/service totals, and the headline charge_total) are recomputed and rolled up automatically.

Every item endpoint returns the parent rental (under the rental key) with its refreshed totals — include ?include=items (or items.assets) when reading to see the line rows themselves.

Optional lines (is_optional = true) still claim availability but are excluded from all charge totals.

Each barcoded line also reports its bulk-line fulfilment progress via dispatched_quantity and returned_quantity (decimal strings) — the quantities physically booked out and checked back in — so the UI can show dispatch progress without loading the asset rows.

A quantity reduction is rejected (422) when the new quantity would drop below the number of barcoded assets already allocated to the line, or below the line's dispatched_quantity. Deallocate or return units first.

Add Line Item#

POST /api/v1/rentals/{id}/items

Returns the rental with refreshed totals under the rental key (201 Created).

Update Line Item#

PATCH /api/v1/rentals/{id}/items/{item}

Accepts any subset of the fields below; each provided field dispatches its own lifecycle event in turn (quantity → price → discount → dates → optional → substitution).

Returns the rental with refreshed totals.

Remove Line Item#

DELETE /api/v1/rentals/{id}/items/{item}

Releases the line's availability demand, removes the row, and rolls the totals back down. Returns the rental with refreshed totals (200 OK).

Asset Allocation#

Barcoded line items track which specific physical assets (assets) are committed to them. Each allocation pins one asset to a line, increments the stock level's allocated quantity, and transitions the line's availability demand from a single quantity-based demand to one asset-specific demand per allocated unit (the quantity-based demand shrinks by the number allocated). Deallocation reverses this.

Allocation is permitted while the rental is open (a Reserved quotation or an Order). The asset must belong to the line's catalogue item, be barcoded, and be free for the line's window — otherwise a 422 is returned. Allocations carry no body beyond the asset id; the asset assignment is returned under the singular asset key.

Allocate Asset#

POST /api/v1/rentals/{id}/items/{item}/assets

Body: asset_id (required). Fires AssetAllocated. Returns the new assignment (201 Created).

Update Asset#

PATCH /api/v1/rentals/{id}/items/{item}/assets/{asset}

Mutates an existing assignment. The action field (required) selects the operation:

An invalid status transition (e.g. preparing an already-prepared asset, dispatching an unallocated asset, or dispatching on a quote rather than an order) yields a 422. Returns the updated assignment (200 OK).

The fulfilment actions auto-promote the parent rental's aggregate status — see Dispatch & Return.

Deallocate Asset#

DELETE /api/v1/rentals/{id}/items/{item}/assets/{asset}

Optional body: reason. Fires AssetDeallocated — removes the assignment row, decrements the asset's allocated quantity, and reverts the freed unit to a quantity-based demand. Allowed only while the asset is Allocated or Prepared; otherwise 422. Returns 204 No Content.

Quick Allocate (batch)#

POST /api/v1/rentals/{id}/quick_allocate

Body: allocations — a non-empty array of {rental_item_id, asset_id} pairs. Every allocation fires inside a single atomic commit, so a failure on any one (asset unavailable, wrong catalogue item, or allocating beyond the line's quantity) rolls back the whole batch. All line items must belong to the rental. Returns the rental with its items + assets (200 OK).

Quick Prepare (batch)#

POST /api/v1/rentals/{id}/quick_prepare

Body: asset_ids — a non-empty array of asset-assignment ids, plus optional prepared_at. Every asset is prepared (Allocated → Prepared) inside a single atomic commit, so a failure on any one (an asset not in the Allocated status) rolls back the whole batch. All assets must belong to the rental. Returns the rental with its items + assets (200 OK).

Dispatch & Return#

Once a rental is an order, its line items move through the fulfilment cycle — out of the warehouse on dispatch, back on return, then condition-checked. Barcoded lines track this per physical asset (via the asset actions above); bulk (non-barcoded) lines track it as aggregate quantities on the line.

Aggregate auto-promotion#

Every dispatch/return/check re-derives the rental's order sub-status from the state of all its items (the "lowest common denominator") and, when it changes, fires a distinct RentalStatusPromoted event — a real, audited status change with its own timestamp, not a silent column write:

A dispatch before the line's planned start pulls that asset's availability demand start back to the actual dispatch time; a return moves the demand end to the actual return time (with turnaround applied off the real return) and releases availability immediately on scan — there is no finalisation gate.

Bulk-line fulfilment#

PATCH /api/v1/rentals/{id}/items/{item}/fulfilment

Dispatch, return, or adjust a non-barcoded line. The action field (required) selects the operation:

Partial dispatch/return is first-class: 60 m of a 100 m cable line can go out now and 40 m later. Over-dispatch (beyond the requested quantity), over-return (beyond what is out), or adjusting below the dispatched quantity each yield a 422. The line's effective demand is quantity - returned_quantity. Returns the updated line (200 OK).

Quick Book-Out (batch)#

POST /api/v1/rentals/{id}/quick_book_out

Body: asset_ids — a non-empty array of asset-assignment ids, plus optional dispatched_by, vehicle_id, dispatched_at. Every asset is dispatched inside a single atomic commit (a failure on any one rolls back the batch), and the order's aggregate status promotes once consistently. All assets must belong to the rental. Returns the rental with its items + assets (200 OK).

Quick Check-In (batch)#

POST /api/v1/rentals/{id}/quick_check_in

Body: asset_ids (required array), optional received_by, return_warehouse_id, returned_at, and finalise (boolean). Each asset is returned in one atomic commit; when finalise is true each return is immediately condition-checked (Good), clearing the check-in queue in a single pass. Returns the rental with its items + assets (200 OK).

Rental Costs#

Costs are ad-hoc charges that sit alongside the priced line items — delivery, crew labour, surcharges, insurance, loss/damage recovery, etc. Unlike line items they are not priced by the rate engine: each carries its own amount (per unit). Costs are taxed exactly like line items (inclusive/exclusive, line-level rounding) and rolled into the rental totals.

Each cost's net is routed into an cost category bucket by cost_type:

Regardless of type, every non-optional cost also feeds charge_excluding_tax_total, tax_total, charge_including_tax_total, and the headline charge_total. Optional costs (is_optional = true) are excluded from all totals. Every cost endpoint returns the parent rental (under the rental key) with its refreshed totals; include ?include=costs when reading to see the cost rows.

Add Cost#

POST /api/v1/rentals/{id}/costs

Returns the rental with refreshed totals under the rental key (201 Created).

Update Cost#

PATCH /api/v1/rentals/{id}/costs/{cost}

Accepts any subset of the fields below; omitted fields are left untouched.

Returns the rental with refreshed totals.

Remove Cost#

DELETE /api/v1/rentals/{id}/costs/{cost}

Removes the cost row and rolls the totals back down. Returns the rental with refreshed totals (200 OK).

Set Deal Price#

POST /api/v1/rentals/{id}/deal_price

Replaces the engine-computed headline charge_total with the manual override. The per-type and tax totals continue to reflect the line items. Returns the rental.

Rejected (422) on a locked order — like a line price override or discount, setting a deal price changes the effective charge and is blocked while the order's FX/tax locks are in place. Release the locks (POST /api/v1/rentals/{id}/unlock_locks) first.

Clear Deal Price#

DELETE /api/v1/rentals/{id}/deal_price

Clears the manual override, reverting charge_total to the engine-computed gross total. Returns the rental. Also rejected (422) on a locked order.

Quote Versions#

A quotation can carry multiple versions — sequential revisions (each new revision supersedes its parent) and parallel alternatives (concurrent options the customer chooses between). Exactly one version is active at any time: the rental's totals, line-item scope, and availability demand all follow the active version. Versions are a sub-resource of a rental — there is no top-level versions endpoint. They reuse the rentals:read / rentals:write abilities and the rentals.view / rentals.edit permissions.

A version's status is one of 0 Draft, 1 Sent, 2 Accepted, 3 Declined, 4 Superseded. Its version_type is 0 Revision or 1 Alternative. Money totals are NET (tax-exclusive) decimal strings.

List Versions#

GET /api/v1/rentals/{id}/versions

Returns the rental's versions (oldest first) in a versions collection. Add ?include=items to embed each version's line items.

Show Version#

GET /api/v1/rentals/{id}/versions/{version}

Returns a single version. Add ?include=items to embed its line items.

Create Version#

POST /api/v1/rentals/{id}/versions

Clones the source version's line items into the new version, which becomes active. A revision supersedes its parent; an alternative coexists. Valid only while the rental is a Quote and within the rentals.max_versions (20) and rentals.max_alternatives (5) caps. Returns the new version (201 Created).

Activate Version#

POST /api/v1/rentals/{id}/versions/{version}/activate

Makes the version active. The rental's totals and item scope switch to it, and availability demand swaps from the previously-active version's items to this one's.

Send / Accept / Decline Version#

POST /api/v1/rentals/{id}/versions/{version}/send
POST /api/v1/rentals/{id}/versions/{version}/accept
POST /api/v1/rentals/{id}/versions/{version}/decline

Advance the version through its customer workflow. send (Draft → Sent) stamps sent_at; accept (Draft/Sent → Accepted) stamps accepted_at; decline (Draft/Sent → Declined) stamps declined_at. An accepted version takes priority when the quotation is converted to an order (an accepted version is confirmed over the active one, and every other version is superseded).

Rename Version#

PATCH /api/v1/rentals/{id}/versions/{version}

Diff Versions#

GET /api/v1/rentals/{id}/versions/{from}/diff/{to}

Returns a diff of the item-level content delta between two versions of the same rental: added (in target, not source), removed (in source, not target), changed (quantity / unit price / discount differ), and net_change (signed total delta). Lines are matched by catalogue item. Both versions must belong to the rental.

Delete Version#

DELETE /api/v1/rentals/{id}/versions/{version}

Removes a version and its line items (204 No Content). The active version and the only remaining version cannot be deleted, and deletion is allowed only while the rental is a Quote.

Error Cases#