Asset Retirements
Retire, void, and reinstate barcoded assets over REST with Ransack filtering and warehouse scoping.
Asset Retirements API
An asset retirement permanently removes a barcoded asset from the fleet — for sale, scrap, or write-off. Retirement is supply-side: a retired asset drops out of stock counts, availability reads, and allocation validation. A retirement records a final Total Cost of Ownership snapshot and, optionally, disposal proceeds.
A retirement is immutable once created. There is no generic update or delete. A retirement is only reversed via reinstate (restores the asset to stock) or void (available for stock-check-sourced discrepancy retirements only).
Endpoints
| Method | URL | Description |
|---|---|---|
| GET | /api/v1/asset_retirements |
List retirements (Ransack filtering, newest disposed first) |
| GET | /api/v1/asset_retirements/{asset_retirement} |
Retrieve a single retirement |
| POST | /api/v1/asset_retirements |
Retire an asset |
| POST | /api/v1/asset_retirements/{asset_retirement}/void |
Void a stock-check-sourced retirement |
| POST | /api/v1/asset_retirements/{asset_retirement}/reinstate |
Reinstate a retired asset |
Authentication
Requires asset-retirements:read (GET) or asset-retirements:write (POST). AssetRetirementPolicy enforces the matching asset-retirements.view / .create / .void permission plus warehouse scoping. Ability and permission are checked independently — a token down-scoped to asset-retirements:read is denied every write endpoint even when the user holds the permission.
Retire an asset
POST /api/v1/asset_retirements
| Field | Type | Required | Description |
|---|---|---|---|
asset_id |
int | Yes | Barcoded asset (asset) being retired |
reason_id |
int | Yes | list entry from the Asset Retirement Reason list |
disposed_at |
date | Yes | Disposal date |
proceeds |
decimal | No | Disposal proceeds as a decimal string (stored in minor units) |
currency_code |
string | No | ISO 4217 code; defaults to base currency |
notes |
string | No | Free-text note |
force |
bool | No | Override active/future bookings (requires the displacement permission) |
Active or future bookings block retirement unless force is set and the caller holds the displacement override permission. A barcoded repair write-off flows through this same single path.
Void and reinstate
POST /api/v1/asset_retirements/{asset_retirement}/void
POST /api/v1/asset_retirements/{asset_retirement}/reinstate
void reverses only retirements sourced from a stock-check discrepancy; voiding a general retirement returns 422. reinstate reverses any retirement and restores the asset to stock, accepting an optional notes field. Both return the updated retirement.
Response shape
AssetRetirementData emits proceeds as a decimal string. Collection key: asset_retirements (with meta); singular: asset_retirement. Includes: asset, creator, voider via ?include=.
Filtering
Ransack-compatible predicates on asset_id, reason, disposed_at, proceeds, currency_code, source_type, source_id, created_by, voided_at, voided_by, created_at, updated_at — e.g. ?q[reason_eq]=Sold, ?q[voided_at_null]=true.
Webhooks
asset_retirement.created, asset_retirement.voided (direct void only), asset_retirement.reinstated — see Webhooks.