Fixed assets
Fixed assets
Keep the fixed asset register through the API: create a draft asset, register
it (which posts its acquisition and the depreciation it has built up so far),
depreciate it month by month and dispose of it. Every posting goes through the
same fixed-asset services as the Fixed assets pages in Cybooks, and
depreciation is straight-line.
The same operations power the Cybooks MCP server. Each REST endpoint below
names its MCP tool; the fixed-asset tools are reached through
cybooks_search_capabilities "fixed asset" and run with
cybooks_read_capability or cybooks_write_capability.
Endpoints
| Endpoint | MCP tool | Scope | Permission |
|---|---|---|---|
GET /v1/fixed-asset-types | cybooks_list_fixed_asset_types | fixed-assets:read | view_fixed_assets |
POST /v1/fixed-asset-types | cybooks_create_fixed_asset_type | fixed-assets:write | create_fixed_assets |
GET /v1/fixed-assets | cybooks_list_fixed_assets | fixed-assets:read | view_fixed_assets |
GET /v1/fixed-assets/{id} | cybooks_get_fixed_asset | fixed-assets:read | view_fixed_assets |
POST /v1/fixed-assets | cybooks_create_fixed_asset | fixed-assets:write | create_fixed_assets |
PATCH /v1/fixed-assets/{id} | cybooks_update_fixed_asset | fixed-assets:write | update_fixed_assets |
DELETE /v1/fixed-assets/{id} | cybooks_delete_fixed_asset | fixed-assets:write | delete_fixed_assets |
POST /v1/fixed-assets/{id}/register/preview | cybooks_preview_fixed_asset_registration | fixed-assets:action | update_fixed_assets |
POST /v1/fixed-assets/{id}/register | cybooks_register_fixed_asset | fixed-assets:action | update_fixed_assets |
POST /v1/fixed-assets/{id}/depreciate/preview | cybooks_preview_fixed_asset_depreciation | fixed-assets:action | update_fixed_assets |
POST /v1/fixed-assets/{id}/depreciate | cybooks_depreciate_fixed_asset | fixed-assets:action | update_fixed_assets |
POST /v1/fixed-assets/{id}/dispose/preview | cybooks_preview_fixed_asset_disposal | fixed-assets:action | update_fixed_assets |
POST /v1/fixed-assets/{id}/dispose | cybooks_dispose_fixed_asset | fixed-assets:action | update_fixed_assets |
Amounts are two-decimal strings in the company's base currency. Every write
needs an Idempotency-Key; an update, a delete and every posting also need the
asset's ETag as Cybooks-If-Match (or the standard If-Match). Each posting is a pair: the preview shows the
exact journals and returns a confirmation_token, and the commit sends that
token with the same Idempotency-Key. If the asset or the journals changed
after the preview, the commit answers 412: preview again.
The asset type holds the accounts
An asset type carries the three accounts its assets post to: the fixed asset
(cost) account, accumulated depreciation and depreciation expense. A type
without the two depreciation accounts (is_non_depreciable: true, for land)
is never depreciated. List the types first and reuse one where it fits.
Useful life: years, months or a yearly rate
Give the useful life one way, on create or on a draft update:
| Field | Use it for | Example |
|---|---|---|
useful_life_years | A whole number of years, 1 to 100 | 5 |
useful_life_months | A life that is not a whole number of years, 12 to 1,200 months | 400 (33 years and 4 months) |
rate_percent | A yearly straight-line rate, 1 to 100 | 3 (= 400 months) |
A rate is stored as months, so it must come to a whole number of months: 3%
is 400 months and 2.5% is 480, but 7% would be 171.43 months, so send
useful_life_months: 171 instead. Sending more than one of the three, or a
rate that is not whole months, answers 422 with invalid_useful_life.
Without any of them a new asset takes its type's default life in years.
The asset reads back with all three: useful_life_years (the whole years, 33
for a 400-month life), useful_life_months (the life the depreciation runs
over) and rate_percent ("3.00"). Each month's depreciation is the
remaining depreciable amount divided by the months left, so a cost of
85,750.00 over 400 months depreciates 214.38 a month and is fully written down
in month 400.
Registering an asset
register/preview shows the journals, then register posts them:
- Acquisition (an
opening_balanceorotherasset): Dr fixed asset,
Cr Opening Balance Equity (or theacquisition_credit_account_idof an
otherasset), dated the purchase date or the opening balance date. A draft
made from a bill has no acquisition journal: the bill already booked it. - Catch-up depreciation: every month from the depreciation start to this
month, one journal per month, dated the last day of the month it covers
(Dr depreciation expense, Cr accumulated depreciation), exactly as the monthly
run would have posted it. An asset registered after a year end therefore puts
last year's depreciation in last year and this year's in this year.
Every month the catch-up posts to must be open. If any is closed by the period
lock or the hard lock, nothing posts and the answer is 422 with
fixed_asset_catch_up_period_locked, listing every closed month in
error.fields.locked_periods (for example ["2025-03", "2025-04"]). Reopen
those months, or ask the accountant, before registering.
A filed VAT or OSS period does not close these months. Registration journals
(the acquisition, the opening accumulated depreciation and each catch-up month)
carry no VAT and change no VAT or OSS return figure, so they post into a filed
period, and each one dated there is recorded under Settings → Closed-period
exceptions. The one exception is a journal that would post to a VAT account:
the asset type's depreciation or accumulated depreciation account, or the
credit account of an other acquisition. In a filed period that journal is
refused like a closed one, and the message names the account.
The monthly run then depreciates each later month on its last day; a single
month can also be posted with depreciate/preview and depreciate.
Assets owned before the books started
For an opening_balance asset the company owned before its books started in
Cybooks, send its opening position on both register/preview and register:
opening_balance_date: either the last day before the books start
(2024-12-31for books from 1 January 2025) or the books-start date itself
(2025-01-01, the date the ledger's opening balance journals carry). Both
mean the same position; the journals are dated the date you send.opening_accumulated_depreciation: the depreciation charged up to the month
end before the books start, from the last audited accounts.
Registration then posts the acquisition and the opening accumulated
depreciation (Dr Opening Balance Equity, Cr accumulated depreciation) on that
date, and every later month to depreciation expense in its own period over the
remaining life. Without an opening position the depreciation to date is
derived from the depreciation start date and posts as one entry dated today
against Opening Balance Equity.
A position that does not fit the asset answers 422 with
invalid_opening_position and names the field: a date that is neither a month
end nor the first of a month, a date in the future or before the purchase
date, more depreciation than the cost less the residual value, none although
depreciation began before the books started, or a useful life that ended
before the opening date with value still left.
Worked example: a building depreciated at 3% a year
A company's books start on 1 January 2025. It bought an apartment on
12 January 2022 for 85,750.00 and depreciates it at 3% a year; the 2024
audited accounts show 7,719.50 of accumulated depreciation.
-
Find the type with
GET /v1/fixed-asset-types(Buildings), or create one. -
Create the draft with an
Idempotency-Key:POST /v1/fixed-assets { "fixed_asset_type_id": "<Buildings type id>", "name": "Apartment", "acquisition_type": "opening_balance", "purchase_date": "2022-01-12", "purchase_price": 85750, "residual_value": 0, "rate_percent": 3 }The answer shows
useful_life_months: 400,useful_life_years: 33and
rate_percent: "3.00".useful_life_months: 400does the same. -
Preview the registration with a new
Idempotency-Key:POST /v1/fixed-assets/<id>/register/preview { "opening_balance_date": "2024-12-31", "opening_accumulated_depreciation": 7719.50 }The journals are the acquisition and the opening accumulated depreciation
on 2024-12-31 (36 months, 2022-01 to 2024-12), then one
catch_up_depreciationjournal a month from 2025-01-31 onwards: the
78,030.50 left over the 364 months left is 214.37 a month, 2,572.44 in 2025.
Keep theconfirmation_tokenand theetag. -
Register with the same body plus the
confirmation_token, the same
Idempotency-Key, and theetagasCybooks-If-Match.
Over MCP the same steps are cybooks_list_fixed_asset_types,
cybooks_create_fixed_asset, cybooks_preview_fixed_asset_registration and
cybooks_register_fixed_asset, run with cybooks_write_capability.
Disposing of an asset
dispose/preview and dispose take disposal_date, disposal_method
(sale, scrap, donation or exchange), disposal_proceeds, the proceeds
account and the gain or loss account (never a revenue account, IAS 16.68). The
months not yet depreciated catch up to the disposal date in one journal, then
the disposal journal removes the cost and the accumulated depreciation and
books the gain or loss.
Errors
| Code | Status | Meaning |
|---|---|---|
invalid_useful_life | 422 | More than one of useful_life_years, useful_life_months and rate_percent, or a rate that is not a whole number of months. |
invalid_opening_position | 422 | The opening position does not fit the asset; the field at fault is named. |
fixed_asset_catch_up_period_locked | 422 | A month the registration's catch-up depreciation would post to is closed by the period lock or the hard lock (or is in a filed VAT/OSS period while the depreciation would post to a VAT account). error.fields.locked_periods lists every closed month. Nothing was posted. |
period_locked | 422 | Another date (the acquisition, the opening balance date, the disposal or this month's depreciation) falls in a closed period. A filed VAT/OSS period alone does not close these VAT-free journals, unless the journal would post to a VAT account, which the message then names. The message names the first open date. |
fixed_asset_not_draft | 409 | Only a draft can be registered or deleted. |
fixed_asset_field_locked | 422 | A registered asset only takes name, description and serial_number. |
fixed_asset_not_disposable | 409 | Only a registered or fully depreciated asset can be disposed of. |
fixed_asset_depreciation_gap | 409 | Earlier months are not depreciated while the disposal month already is: post the missing months in Cybooks first. |
depreciation_not_applicable | 422 | Nothing to depreciate this month: already depreciated, before the depreciation start, fully depreciated or not depreciated (land). |
fixed_asset_type_incomplete | 422 | The asset type is missing an account the posting needs. |
base_currency_only | 422 | Fixed assets are recorded in the base currency. |
fixed_asset_number_conflict | 409 | Another asset was registered at the same moment. Retry. |
fixed_asset_posting_refused | 422 | The ledger refused the posting; the message says why. |
Events
fixed_asset.created, fixed_asset.updated, fixed_asset.deleted,
fixed_asset.registered, fixed_asset.depreciated, fixed_asset.disposed and
fixed_asset_type.created (see Event types).
Updated 16 days ago
