Owner's Money
Owner's Money: a director's private expense paid by the company
A director or shareholder has two personal accounts in Cybooks, shown on the Owner's Money screen: what they owe the company, and what the company owes them. When the company pays something private for them (a hotel, a streaming subscription), or they pay money in, the bank line belongs on one of those accounts.
Book it with relatedParty.reconcile (MCP: cybooks_preview_related_party_reconciliation, then cybooks_reconcile). Do not categorize the line to "Loans to directors" with a placeholder supplier: that posts the right journal, but the person's personal account never moves. Their Owner's Money balance, the year-end director checks and the related-party disclosures all read the personal account.
| Step | Operation | MCP tool |
|---|---|---|
| Find the person | GET /related-parties?filter[role]=director | cybooks_list_related_parties |
| Find the line | GET /bank-transactions | cybooks_list_bank_transactions |
| Preview | POST /related-parties/{id}/reconcile/preview | cybooks_preview_related_party_reconciliation |
| Commit | POST /related-parties/{id}/reconcile | cybooks_reconcile |
| Check | GET /related-parties/{id}/owner-money | cybooks_get_related_party_owner_money |
Finding the person
GET /related-parties (scope related-parties:read, permission related-parties.view) takes six filters:
| Filter | Values | Default |
|---|---|---|
filter[id] | a related party id | every person |
filter[role] | director, shareholder, employee, other_related | every role |
filter[status] | active (not archived), archived, all | active |
filter[party_status] | active, inactive: the person's own status field | either |
filter[search] | the whole phrase, as typed, at most 191 characters, matched as one piece of the name (% and _ match themselves) | every name |
filter[updated_since] | a date-time: only people changed since then | every person |
filter[status] is about archiving, not the person's own status field: an active-filter list can still hold a person whose status is inactive. Owner's Money takes an active director or shareholder, so add filter[party_status]=active: GET /related-parties?filter[role]=director&filter[party_status]=active&filter[search]=Andreas. Without filter[role] one read lists directors and shareholders alike (and anyone else), each with its roles. Over MCP the list is not in the tool list: run it through cybooks_read_capability with the operation relatedParty.index (tool name cybooks_list_related_parties), the filters in query.filter, for example {"capability": "relatedParty.index", "arguments": {"query": {"filter": {"role": "shareholder"}}}}.
To turn a name into an id, cybooks_resolve_references takes {"type": "related_party", "query": "Andreas"}: it matches the name of a related party that is not archived, under the same related-parties.view permission, and returns resolved, ambiguous (the candidates, never a guess) or not_found.
Scopes: related-parties:action for the preview and the commit, related-parties:read for the check. Permissions: related-parties.update, owner-money.view and owner-money.settle to book, related-parties.view and owner-money.view to read. Moving a line that is already booked (replace_booking_id) undoes a bank booking, so it also needs what bankTransaction.booking.undo needs: the update_bank_accounts permission and, on REST, the bank-transactions:action scope. cybooks_playbooks returns these steps as the owner_money_private_expense playbook.
Worked example: the company paid a director's hotel
The company's bank account paid Chrysomare Beach Hotel €757.16 on 13 March for Sarah, a director. The line is still uncategorized.
1. Preview. Send an Idempotency-Key; you reuse it on the commit.
POST /api/v1/related-parties/89d3c846-…/reconcile/preview
Idempotency-Key: owner-money-ecf629c0
Content-Type: application/json
{ "transaction_id": "ecf629c0-…" }{
"data": {
"related_party_id": "89d3c846-…",
"transaction_id": "ecf629c0-…",
"replace_booking_id": null,
"effects": {
"classification": { "direction": "related_party_owes_company", "amount": "757.160000", "currency_id": "…" },
"journal": {
"transaction_type": "categorize",
"date": "2026-03-13",
"debit_chart_of_account_id": "15",
"credit_chart_of_account_id": "…",
"debit_source_amount": "757.160000",
"credit_source_amount": "757.160000",
"debit_base_amount": "757.16",
"credit_base_amount": "757.16",
"exchange_rate": "1"
},
"replaced_booking": null,
"result": "reconcile_as_related_party_owner_money"
},
"confirmation_token": "…",
"expires_in": 300
}
}A payment out raises what the person owes the company: Dr Loans to directors (or Loans to shareholders), Cr the bank account. Money in raises what the company owes them (Directors' current account, or Shareholder notes payable). Owner's Money never carries VAT and records no supplier or customer: the person is the counterparty, and the merchant stays in the bank line's own name and description.
2. Commit. Same body, the preview's confirmation_token, the same Idempotency-Key, and the related party's ETag as Cybooks-If-Match (or the standard If-Match). The token expires after 5 minutes.
Two headers the commit gets wrong most often
Idempotency-Keyis the preview's key, sent again. The confirmation token is bound to the key it was issued under: a commit with a new key is refused with 422 (confirmation_tokendoes not match). Use one key per line, on that line's preview and commit.Cybooks-If-Matchis the related party's ETag, not the bank line's. Read it fromGET /related-parties/{id}(relatedParty.show; over MCP,response.etagofcybooks_get_related_party). It advances with every reconcile and settlement of that person, so after a commit use theETagthe commit returned (MCP: itsresponse.etag), or read the person again. A stale ETag is refused with 412.Over MCP the two are the
idempotency_keyandif_matcharguments ofcybooks_reconcile.
POST /api/v1/related-parties/89d3c846-…/reconcile
Idempotency-Key: owner-money-ecf629c0
Cybooks-If-Match: "3f9c1a7d0b2e4c51-v4"
{ "transaction_id": "ecf629c0-…", "confirmation_token": "…" }{
"data": {
"id": "01a14e61-…",
"type": "related_party_reconciliation",
"related_party_id": "89d3c846-…",
"transaction_id": "ecf629c0-…",
"direction": "related_party_owes_company",
"amount": "757.16",
"currency": "EUR",
"replaced_booked_transaction_id": null,
"version": 5
}
}id is the bank booking. The response carries a new ETag for the related party: use it as Cybooks-If-Match on the next line.
3. Check.
GET /api/v1/related-parties/89d3c846-…/owner-money?include_movements=true{
"data": {
"related_party_id": "89d3c846-…",
"type": "related_party_owner_money",
"currency": "EUR",
"they_owe_company": "6757.16",
"company_owes_them": "0.00",
"net_balance": "6757.16",
"balance_direction": "related_party_owes_company",
"oldest_unsettled_at": "2026-03-13",
"personal_accounts": [
{ "kind": "asset", "meaning": "they_owe_company", "chart_of_account_id": "15", "balance": "6757.16", "movement_count": 2 },
{ "kind": "liability", "meaning": "company_owes_them", "chart_of_account_id": "350", "balance": "0.00", "movement_count": 0 }
],
"movements": [
{
"date": "2026-09-03", "account_kind": "asset", "meaning": "they_owe_company", "balance_effect": "increase",
"amount": "6000.00", "source": "bank_line", "bank_transaction_id": "ab71f899-…", "bank_booked_transaction_id": "…"
},
{
"date": "2026-03-13", "account_kind": "asset", "meaning": "they_owe_company", "balance_effect": "increase",
"amount": "757.16", "source": "bank_line", "bank_transaction_id": "ecf629c0-…", "bank_booked_transaction_id": "01a14e61-…"
}
],
"movements_truncated": false
}
}The balances are the figures of the app's Owner's Money screen. Movements are newest first, at most 500; narrow them with date_from and date_to (YYYY-MM-DD). source is bank_line for a company bank or cash line (with its ids; a salary line you may not see keeps its amount but its ids are null), settlement for a repayment between a bank account and the personal account, and other for anything else (for example a bill the person paid).
A line whose booking was undone
bankTransaction.booking.undo (and Undo in the app) removes a booking and its journal, but a bank-feed line keeps the account and contact it was booked with, so the row offers them again. That is a draft, not a booking: nothing in the ledger reads it. Owner's Money books such a line like an uncategorized one (no replace_booking_id) and replaces the draft: the line ends with the person's personal account, no supplier or customer, no tax rule and no rule. The same goes for an account a rule or a bank-file parser prefilled.
So a line can be moved in two steps instead of one: undo its booking, then preview and commit relatedParty.reconcile with just transaction_id. Use this for a booking replace_booking_id does not take (a bill or invoice match, a split, a fee). Two exceptions. In a closed or filed VAT period, do not undo first: the one-step preview names the period (related_party_reclassify_period_locked, related_party_reclassify_vat_filed), while an undo there reverses a payment today (a bill reopens) and the Owner's Money entry could then never be posted on the line's date. And a dividend is undone only in Cybooks (see related_party_reclassify_dividend_payment below).
A salary line you may not see (no payroll access) is refused with 403 before anything about it is said. Without replace_booking_id these refusals are 422 with the code in error.code and the sentence in error.message (<field>: <sentence>) and error.fields:
| Code | Field | Meaning |
|---|---|---|
related_party_reconcile_line_has_booking | payment_account_transaction_id | Another booking still holds the line: one not yet reconciled, or one sent back for review whose journal is still in the books (even when the line shows no account). Undo it first |
related_party_reconcile_line_still_posted | payment_account_transaction_id | No booking holds the line, but the books still carry it: a journal for it stayed posted when its booking was deleted (for example by voiding a dividend whose payment had been undone on this line). Booking it again would count it twice: have the ledger corrected first |
bank_line_already_reconciled | payment_account_transaction_id | A booking reconciled the line while the commit ran. A booking made before the commit is refused first with 409 related_party_reconcile_line_booked (below) |
related_party_reconcile_line_changed | payment_account_transaction_id | The line changed since the preview. Preview again |
bank_line_changed | payment_account_transaction_id | The line was deleted, undone or moved while the commit ran. Read it again |
related_party_reconcile_currency | currency_id | A foreign-currency line: Owner's Money takes base-currency lines only |
related_party_not_director_or_shareholder | related_party_id | The person is not an active director or shareholder |
related_party_reconcile_line_type | payment_account_transaction_id | Not an incoming or outgoing line |
related_party_reconcile_not_bank_line | payment_account_transaction_id | Not a line of a company bank or cash account, or its account was deleted |
payment_account_unavailable | payment_account_id | The line's account was deleted, or is no longer a bank or cash account, while the commit ran |
period_locked | date | The line's date is on or before the date the books are closed through or the VAT lock date, so nothing was posted. Checked by the commit (the preview does not read the date); the message is period_locked: <sentence>. The app's Owner's Money action can post this VAT-free entry into a VAT-locked period while the books are open; the public API cannot |
A line that is booked and reconciled is refused before any of these with 409 related_party_reconcile_line_booked (below).
Moving a line that is already categorized
A line categorized to Loans to directors with a placeholder supplier (or to any other account by a plain categorization) is moved by sending its booking as replace_booking_id. Without it, the preview refuses with related_party_reconcile_line_booked and names the booking in error.fields.booked_transaction_ids:
{
"error": {
"type": "conflict_error",
"code": "related_party_reconcile_line_booked",
"message": "related_party_reconcile_line_booked: This bank line is already booked. …",
"fields": { "booked_transaction_ids": ["01a14e5f-76b9-…"] }
}
}Preview again with { "transaction_id": "8ea1be10-…", "replace_booking_id": "01a14e5f-76b9-…" }. The preview's effects.replaced_booking shows what the commit undoes:
"replaced_booking": {
"booked_transaction_id": "01a14e5f-76b9-…",
"account_id": "15",
"tax_rule_id": "…",
"counterparty_type": "vendor",
"counterparty_id": "019c9bc1-…",
"amount": "20.000000",
"date": "2026-01-04",
"journal_effect": "removed"
},
"result": "reclassify_as_related_party_owner_money"The commit (same body plus the token) runs in one transaction: it undoes the booking the way the app's undo and bankTransaction.booking.undo do (its journal is removed), clears the line's supplier, account and tax rule, and books the line to the personal account. If any step fails, nothing changes. For a line first booked to account 15, the ledger total of account 15 stays the same and the personal account moves by the line's amount. The result's replaced_booked_transaction_id names the undone booking. Change events: reconciliation_match.reversed and booked_transaction.undone for the undo, then booked_transaction.created and related_party.reconciled.
Only a plain categorization moves. These refusals name their code in error.code and at the start of the message:
| Code | Status | Meaning |
|---|---|---|
related_party_reclassify_booking_mismatch | 422 | replace_booking_id is not a booking of this line |
related_party_reclassify_not_plain_booking | 409 | The booking is a bill or invoice match, a transfer, a split or a fee. Undo it (bankTransaction.booking.undo), then book the line without replace_booking_id |
related_party_reclassify_withholding_remittance | 409 | The line pays withheld dividend tax (SDC or GHS) to the Tax Department: a plain categorization to a withholding payable, or Reconcile's booking against the dividend's withholding. If it was not a tax payment, undo the booking in Cybooks first, then book the line without replace_booking_id |
related_party_reclassify_dividend_payment | 409 | The line pays a dividend recorded in Dividends. A bank line matched to the dividend: undo that payment on the bank line in Cybooks, which reverses it and reopens the dividend (the public API cannot undo a dividend payment), then book the line without replace_booking_id. The cash line Dividends makes when it pays from an account with no statements is never undone on the line, which would remove the payment and leave the dividend paid: void the dividend in Dividends if the money was not a dividend. A plain categorization to Dividend disbursed or Dividends payable with no dividend behind it moves like any other |
related_party_reclassify_already_related_party | 409 | The line is already booked to a director or shareholder |
related_party_reclassify_manual_line | 409 | The line was entered in Cybooks, and undoing its booking deletes it |
related_party_reclassify_currency | 409 | A foreign-currency line: Owner's Money takes base-currency lines only |
related_party_reclassify_period_locked | 409 | The booking is in a closed period. Named before any refusal that says to undo the booking |
related_party_reclassify_vat_filed | 409 | The booking is in a filed VAT period, which is never changed. Named before any refusal that says to undo the booking |
A line, booking or person that changed after the preview is refused with 412 (preview again). A booking that was undone or replaced in the meantime is no longer a booking of the line, so the commit refuses it with 422 related_party_reclassify_booking_mismatch: read the line's bookings and preview again. A token sent with a different Idempotency-Key is refused with 422, and a commit repeated with the same key returns the stored response without booking again. Once a placeholder supplier has no lines left, archive it with vendor.archive.
Recipe for many lines
- Read the person once (
GET /related-parties/{id}) and keep itsETag. - For each line: read its bookings (
GET /bank-transactions/{id}/booked-transactions, MCPcybooks_list_bank_transaction_bookings), pick a newIdempotency-Keyfor this line, preview with that key and the booking's id asreplace_booking_id, then commit with the same key and the currentETagasCybooks-If-Match. - Keep the
ETagthe commit returns for the next line. Run the lines one at a time: every commit advances the related party's version, so a commit sent with an older ETag is refused with 412.
Then compare they_owe_company with the ledger balance of the Loans to directors account.
Updated 11 days ago
