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

Opportunities API

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

Opportunities use a two-axis model: a state (Draft, Quotation, Order) and a per-state status (e.g. Quotation/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 opportunities:read (GET) or opportunities:write (POST/PUT/DELETE) ability, alongside the matching opportunities.view / opportunities.create / opportunities.edit / opportunities.delete permission.

Opportunity Field Reference#

All opportunity responses include the following fields under the opportunity 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 opportunity:

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

Two-Axis State Model#

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

List Opportunities#

GET /api/v1/opportunities

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

Filters#

Ransack-compatible q[field_predicate]=value parameters:

Includes#

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

The opportunity'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.

Custom Views#

Apply a saved view with ?view_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 Custom Views API for details.

Sort#

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

Pagination#

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

Show Opportunity#

GET /api/v1/opportunities/{id}

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

The opportunity 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.

Opportunity Assets#

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

A flat, paginated list of every per-asset assignment across all of the opportunity's line items (the opportunity_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, opportunity_item_id, stock_level_id, status + status_label, lifecycle timestamps).

Requires opportunities.view / opportunities: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.

Opportunity Availability#

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

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

Each entry: opportunity_item_id, product_id, store_id, requested_quantity, available_for_item, shortage_quantity, has_shortage, from, to.

Requires opportunities.view / opportunities:read.

Opportunity Activity#

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

A paginated, newest-first read of the audit trail (action_logs) scoped to this opportunity, 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 Opportunity#

POST /api/v1/opportunities

Creates the opportunity as a Draft / Open. A zero-padded RMS number (e.g. "0000000042") is auto-generated from a per-store 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 opportunity under the opportunity key.

Update Opportunity#

PUT /api/v1/opportunities/{id}

Partial update of editable header fields. All fields are optional — omitted fields are left unchanged. A closed/terminal opportunity (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 store's team if a date must be removed.

Fulfilment Flags#

Delivery & Collection#

Delete Opportunity#

DELETE /api/v1/opportunities/{id}

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

Convert to Quotation#

POST /api/v1/opportunities/{id}/convert_to_quotation

Transitions a Draft opportunity to a Quotation / Provisional. Returns the updated opportunity under the opportunity key. An invalid transition (not currently a Draft) yields a 422.

Convert to Order#

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

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

Change Status#

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

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

Returns the updated opportunity under the opportunity key.

Error Cases#

Available Actions#

GET /api/v1/opportunities/{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 opportunities.view / opportunities:read.

Response#

{
    "available_actions": [
        {
            "action": "convert_to_order",
            "label": "Convert to Order",
            "available": true,
            "disabled": false,
            "reason": null,
            "reason_code": null
        },
        {
            "action": "revert_to_draft",
            "label": "Revert to Draft",
            "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 Opportunity#

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

Restores a soft-deleted opportunity. 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 opportunity under the opportunity key (200 OK).

Requires opportunities.delete / opportunities:write.

Clone Opportunity#

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

Creates a copy of the opportunity as a new Draft, including its line items, costs, and custom fields. The clone gets a fresh RMS number and is otherwise independent of the source; its source_opportunity_id points back to the original. Returns the new opportunity under the opportunity key (201 Created).

Requires opportunities.create / opportunities:write.

Reinstate#

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

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

Requires opportunities.edit / opportunities:write.

Revert to Quotation#

POST /api/v1/opportunities/{id}/revert_to_quotation

Reverts an open Order (Active) back to a Quotation / Provisional. The opportunity 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 opportunities.edit / opportunities:write.

Revert to Draft#

POST /api/v1/opportunities/{id}/revert_to_draft

Reverts an open, provisional Quotation back to a Draft / Open. Only allowed while the quotation is in the Provisional (open) status — a Reserved or closed quotation cannot be reverted. Returns the updated opportunity.

Requires opportunities.edit / opportunities:write.

Reopen#

POST /api/v1/opportunities/{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 opportunity.

Requires opportunities.edit / opportunities:write.

Unlock Locks#

POST /api/v1/opportunities/{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 opportunity.

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

Lock Rates#

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

Applies FX and tax locks on an opportunity — 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 opportunities.unlock_rates permission and opportunities:write ability. Returns 422 when locks are already active. Returns the updated opportunity.

Restructure Items Tree#

PATCH /api/v1/opportunities/{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 opportunities.edit / opportunities:write. Returns the updated opportunity.

Opportunity Participants#

Participants are members (contacts or staff) attached to an opportunity in a named role — for example, a site contact, a crew chief, or an on-site supervisor. They are RMS-compatible (participants[] in the field set) and returned via ?include=participants.

List (via include)#

GET /api/v1/opportunities/{id}?include=participants

Participants are returned in the participants array on the opportunity. Each entry:

Add Participant#

POST /api/v1/opportunities/{id}/participants

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

Requires opportunities.edit / opportunities:write.

Update Participant#

PATCH /api/v1/opportunities/{id}/participants/{participant}

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

Remove Participant#

DELETE /api/v1/opportunities/{id}/participants/{participant}

Removes the participant. Returns 204 No Content. The {participant} must belong to the opportunity.

Opportunity Items#

Line items are the priced rows of an opportunity. 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 opportunity'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 opportunity (under the opportunity 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 serialised 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 serialised assets already allocated to the line, or below the line's dispatched_quantity. Deallocate or return units first.

Add Line Item#

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

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

Update Line Item#

PATCH /api/v1/opportunities/{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 opportunity with refreshed totals.

Remove Line Item#

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

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

Asset Allocation#

Serialised line items track which specific physical assets (stock levels) 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 opportunity is open (a Reserved quotation or an Order). The asset must belong to the line's product, be serialised, 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/opportunities/{id}/items/{item}/assets

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

Update Asset#

PATCH /api/v1/opportunities/{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 opportunity's aggregate status — see Dispatch & Return.

Deallocate Asset#

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

Optional body: reason. Fires AssetDeallocated — removes the assignment row, decrements the stock level'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/opportunities/{id}/quick_allocate

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

Quick Prepare (batch)#

POST /api/v1/opportunities/{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 opportunity. Returns the opportunity with its items + assets (200 OK).

Dispatch & Return#

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

Aggregate auto-promotion#

Every dispatch/return/check re-derives the opportunity's order sub-status from the state of all its items (the "lowest common denominator") and, when it changes, fires a distinct OpportunityStatusPromoted 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/opportunities/{id}/items/{item}/fulfilment

Dispatch, return, or adjust a non-serialised 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/opportunities/{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 opportunity. Returns the opportunity with its items + assets (200 OK).

Quick Check-In (batch)#

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

Body: asset_ids (required array), optional received_by, return_store_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 opportunity with its items + assets (200 OK).

Opportunity 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 opportunity totals.

Each cost's net is routed into an RMS 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 opportunity (under the opportunity key) with its refreshed totals; include ?include=costs when reading to see the cost rows.

Add Cost#

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

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

Update Cost#

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

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

Returns the opportunity with refreshed totals.

Remove Cost#

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

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

Set Deal Price#

POST /api/v1/opportunities/{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 opportunity.

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/opportunities/{id}/unlock_locks) first.

Clear Deal Price#

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

Clears the manual override, reverting charge_total to the engine-computed gross total. Returns the opportunity. 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 opportunity's totals, line-item scope, and availability demand all follow the active version. Versions are a sub-resource of an opportunity — there is no top-level versions endpoint. They reuse the opportunities:read / opportunities:write abilities and the opportunities.view / opportunities.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/opportunities/{id}/versions

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

Show Version#

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

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

Create Version#

POST /api/v1/opportunities/{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 opportunity is a Quotation and within the opportunities.max_versions (20) and opportunities.max_alternatives (5) caps. Returns the new version (201 Created).

Activate Version#

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

Makes the version active. The opportunity'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/opportunities/{id}/versions/{version}/send
POST /api/v1/opportunities/{id}/versions/{version}/accept
POST /api/v1/opportunities/{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/opportunities/{id}/versions/{version}

Diff Versions#

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

Returns a diff of the item-level content delta between two versions of the same opportunity: 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 product. Both versions must belong to the opportunity.

Delete Version#

DELETE /api/v1/opportunities/{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 opportunity is a Quotation.

Error Cases#