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

EndpointMCP toolScopePermission
GET /v1/fixed-asset-typescybooks_list_fixed_asset_typesfixed-assets:readview_fixed_assets
POST /v1/fixed-asset-typescybooks_create_fixed_asset_typefixed-assets:writecreate_fixed_assets
GET /v1/fixed-assetscybooks_list_fixed_assetsfixed-assets:readview_fixed_assets
GET /v1/fixed-assets/{id}cybooks_get_fixed_assetfixed-assets:readview_fixed_assets
POST /v1/fixed-assetscybooks_create_fixed_assetfixed-assets:writecreate_fixed_assets
PATCH /v1/fixed-assets/{id}cybooks_update_fixed_assetfixed-assets:writeupdate_fixed_assets
DELETE /v1/fixed-assets/{id}cybooks_delete_fixed_assetfixed-assets:writedelete_fixed_assets
POST /v1/fixed-assets/{id}/register/previewcybooks_preview_fixed_asset_registrationfixed-assets:actionupdate_fixed_assets
POST /v1/fixed-assets/{id}/registercybooks_register_fixed_assetfixed-assets:actionupdate_fixed_assets
POST /v1/fixed-assets/{id}/depreciate/previewcybooks_preview_fixed_asset_depreciationfixed-assets:actionupdate_fixed_assets
POST /v1/fixed-assets/{id}/depreciatecybooks_depreciate_fixed_assetfixed-assets:actionupdate_fixed_assets
POST /v1/fixed-assets/{id}/dispose/previewcybooks_preview_fixed_asset_disposalfixed-assets:actionupdate_fixed_assets
POST /v1/fixed-assets/{id}/disposecybooks_dispose_fixed_assetfixed-assets:actionupdate_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:

FieldUse it forExample
useful_life_yearsA whole number of years, 1 to 1005
useful_life_monthsA life that is not a whole number of years, 12 to 1,200 months400 (33 years and 4 months)
rate_percentA yearly straight-line rate, 1 to 1003 (= 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_balance or other asset): Dr fixed asset,
    Cr Opening Balance Equity (or the acquisition_credit_account_id of an
    other asset), 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-31 for 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.

  1. Find the type with GET /v1/fixed-asset-types (Buildings), or create one.

  2. 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: 33 and
    rate_percent: "3.00". useful_life_months: 400 does the same.

  3. 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_depreciation journal 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 the confirmation_token and the etag.

  4. Register with the same body plus the confirmation_token, the same
    Idempotency-Key, and the etag as Cybooks-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

CodeStatusMeaning
invalid_useful_life422More 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_position422The opening position does not fit the asset; the field at fault is named.
fixed_asset_catch_up_period_locked422A 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_locked422Another 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_draft409Only a draft can be registered or deleted.
fixed_asset_field_locked422A registered asset only takes name, description and serial_number.
fixed_asset_not_disposable409Only a registered or fully depreciated asset can be disposed of.
fixed_asset_depreciation_gap409Earlier months are not depreciated while the disposal month already is: post the missing months in Cybooks first.
depreciation_not_applicable422Nothing to depreciate this month: already depreciated, before the depreciation start, fully depreciated or not depreciated (land).
fixed_asset_type_incomplete422The asset type is missing an account the posting needs.
base_currency_only422Fixed assets are recorded in the base currency.
fixed_asset_number_conflict409Another asset was registered at the same moment. Retry.
fixed_asset_posting_refused422The 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).


Did this page help you?