Bank transactions

Bank transactions

A bank transaction is one line of a bank, card, cash or provider account
(bankTransaction.index, bankTransaction.show). This guide covers checking
a month against the bank statement, booking a line to an account
(categorize) or many lines at once (bulk categorize), short answers to
writes, changing a line that is already booked, money back from a supplier
or to a customer, and excluding, including or deleting lines in bulk.
Matching a line to a bill or invoice (reconciliationMatch.create) is in
Settling bills from bank lines. The same
operations power the Cybooks MCP server: each REST endpoint below names its
MCP tool.

Every write below needs an Idempotency-Key (MCP: idempotency_key), and the
ones that change one line need the line's ETag in Cybooks-If-Match (MCP:
if_match). See Authentication for both.

OperationRESTMCP toolScope
bankTransaction.showGET /v1/bank-transactions/{id}cybooks_get_bank_transactionbank-transactions:read
bankTransaction.summaryGET /v1/bank-transactions/summarycybooks_get_bank_transaction_summarybank-transactions:read
bankTransaction.categorizePOST /v1/bank-transactions/{id}/categorizecybooks_categorize_bank_transactionbank-transactions:action
bankTransaction.bulkCategorize.preview, bankTransaction.bulkCategorize, bankTransaction.bulkCategorize.statusPOST /v1/bank-transactions/bulk-categorize/preview, POST /v1/bank-transactions/bulk-categorize, GET /v1/bank-transactions/bulk-categorize/operations/{operationId}cybooks_preview_bulk_categorize_bank_transactions, cybooks_bulk_categorize_bank_transactions, cybooks_get_bulk_categorize_statusbank-transactions:action
bankTransaction.booking.indexGET /v1/bank-transactions/{id}/booked-transactionscybooks_list_bank_transaction_bookingsbank-transactions:read
bankTransaction.booking.undoPOST /v1/bank-transactions/{id}/booked-transactions/{bookingId}/undocybooks_undo_bank_transaction_bookingbank-transactions:action
bankTransaction.bulkExclude.preview, bankTransaction.bulkExcludePOST /v1/bank-transactions/bulk-exclude/preview, POST /v1/bank-transactions/bulk-excludecybooks_preview_bulk_exclude_bank_transactions, cybooks_bulk_exclude_bank_transactionsbank-transactions:action
bankTransaction.bulkInclude.preview, bankTransaction.bulkIncludePOST /v1/bank-transactions/bulk-include/preview, POST /v1/bank-transactions/bulk-includecybooks_preview_bulk_include_bank_transactions, cybooks_bulk_include_bank_transactionsbank-transactions:action
bankTransaction.bulkDelete.preview, bankTransaction.bulkDeletePOST /v1/bank-transactions/bulk-delete/preview, POST /v1/bank-transactions/bulk-deletecybooks_preview_bulk_delete_bank_transactions, cybooks_bulk_delete_bank_transactionsbank-transactions:action

The summary needs the view_bank_accounts permission. Categorize, bulk
categorize, undo, exclude and include need update_bank_accounts; bulk
delete needs delete_bank_accounts. The two other undos below need their
own scope: reconciliationMatch.unmatch the reconciliation:action scope (with
reconcile_transactions, update_bank_accounts, view_bank_accounts,
view_bills and view_vat_returns), transfer.unmatch the
transfers:action scope (with update_bank_accounts). The reads the steps
below look at need their own scope too: transfer.show the transfers:read
scope (with view_bank_accounts), vatReturn.index the reports:read scope
(with view_vat_returns), creditNote.index the credit-notes:read scope
(with view_credit_notes) and vendorCredit.index the vendor-credits:read
scope (with view_vendor_credits).

Checking a month against the statement

GET /v1/bank-transactions/summary (MCP: cybooks_get_bank_transaction_summary,
reached through cybooks_search_capabilities and run with
cybooks_read_capability) counts and sums the lines, so an agent can compare
the month with the statement without paging through every line.

Filter
filter[date_from], filter[date_to]Required, YYYY-MM-DD, inclusive, date_to at most 366 days after date_from.
filter[payment_account_id], filter[direction], filter[currency], filter[reconciliation_state], filter[provider], filter[counterparty_id]Optional, as on GET /v1/bank-transactions.

Missing dates, a date_to before date_from or more than 366 days after it,
an empty filter value or any other filter (id, source_id,
updated_since, q) answer 422 validation_failed. The filters are read
from the URL query only, never from a request body.

The answer has one row per reconciliation state, direction and currency with
lines in the range:

{
  "data": {
    "date_from": "2026-03-01",
    "date_to": "2026-03-31",
    "rows": [
      { "reconciliation_state": "unreconciled", "direction": "incoming", "currency": "EUR", "count": 2, "amount": "120.10", "hidden_count": 0 },
      { "reconciliation_state": "unreconciled", "direction": "outgoing", "currency": "EUR", "count": 2, "amount": "-40.25", "hidden_count": 1 }
    ]
  }
}
  • count is the number of lines GET /v1/bank-transactions lists for the same
    filters.
  • amount is their sum, each line rounded to 2 decimals as the list shows
    it, signed as the list signs a line: money out is negative.
  • hidden_count is the number of salary lines the caller may not see
    (no view_payroll). They are counted in count but left out of amount.
  • Lines of archived accounts are included, as in the list. Lines of
    non-operational account types are not, as in the list.

Requires the bank-transactions:read scope and view_bank_accounts.

Categorize a line

bankTransaction.categorize books a line that no bill or invoice matches to
an account, and posts it to the ledger. The body names:

  • the account, by account_id (the chart-of-accounts id, needed when the
    account has no code) or account_code;
  • the tax rule, by tax_rule_id or tax_code;
  • counterparty_id: a customer on money in, a supplier on money out;
  • memo;
  • tags, optional: tag ids, at most 20, at most one tag from each tag group.

Send the line's ETag from bankTransaction.show (or from the last write on
the line) as Cybooks-If-Match. Posting changes the books, so confirm with
the user first.

Tags

tags puts the tags on the account line of the booking, as the Reconcile
screen does. Each id must be a tag that exists (a deleted tag is refused), and
two tags from one group are refused. Tags are part of the Cybooks plan: without
the tag feature, a non-empty tags is refused with 422 tags_need_plan;
"tags": [] is accepted on any plan. If a tag is deleted after the request was
checked but before the line was booked, nothing is booked and the answer is
422 tags_gone: read the tags again and send ones that still exist. Bulk
categorize takes tags per item the same way.

A categorized line shows its tags as tag_ids on the bank transaction: the
tags on its current categorize booking, without archived tags, sorted. A line
that is not categorized, and a line a salary mask hides, shows []. tag_ids
can be asked for with fields, and the change feed lists tag_ids among
the changed fields of a categorize that wrote tags (and of an undo that
changed them).

A line that is excluded from reconciliation is refused with
422 bank_line_excluded: include it again first (bulk include, below). A line
that is already booked is refused with 409 bank_line_already_booked, which
names its bookings (error.fields.booked_transaction_ids) and the operation
that undoes them (error.fields.undo_operation_id).

Change a line that is already booked

A booked line is not categorized again as it is. Change it only when the user
asked for that line to change, in three steps:

  1. bankTransaction.booking.index lists the line's bookings, each with its
    id.
  2. Undo it with the operation the 409 names in error.fields.undo_operation_id,
    on the id it lists in error.fields.booked_transaction_ids:
    bankTransaction.booking.undo (bookingId, the line's ETag) for a
    categorization of the line or an invoice payment, as Cybooks' Undo does;
    reconciliationMatch.unmatch (preview, then commit) for a bill payment or a
    payment over several bills or invoices; transfer.unmatch (preview, then
    commit, with the transfer's id and the ETag of transfer.show, never *)
    for a leg of a transfer. Check the line's date before you undo (see the
    limits below). The line is open again; read it for its new ETag
    (bankTransaction.booking.undo returns it).
  3. bankTransaction.categorize books it again, with that new ETag and a new
    Idempotency-Key.

Undo has limits. Do not work around a refusal: tell the user.

  • A booking dated in a closed period or a filed VAT period: leave it and ask
    the user first. Undoing a categorization dated on or before the period lock,
    the tax lock date or the hard lock is refused: 422 invalid_request, or
    403 forbidden when the month is closed and the connected person may not
    close periods (manage_period_lock). Neither answer names the period: read
    the line's date. The tax lock date moves when a VAT or OSS return is
    completed in Cybooks; a return completed before the company had one is not
    covered by it, so for a line dated in an earlier VAT period read
    vatReturn.index first and do not undo when period_filed is true for the
    line's date. Reopening a period is the user's decision, not a step to take
    on your own.
  • A payment or a transfer dated in a closed period or a filed VAT period is
    often not refused: for a person who may close periods (in a filed VAT
    period, anyone who may undo), within the current financial year and unless
    the company blocks such reversals, the undo posts its reversal on the
    first open day and gives the line back unbooked, and step 3 is then
    refused, because a new booking takes the lock on the line's own date. The
    line stays unbooked until the user reopens the period. Otherwise it is refused:
    403 forbidden in a closed month for a person without manage_period_lock,
    422 invalid_request when the payment is in an earlier financial year.
    reconciliationMatch.unmatch.preview and transfer.unmatch.preview show it
    (effects.mode is forward_reversal, with effects.reversal_date);
    bankTransaction.booking.undo has no preview.
  • A bill or invoice payment: undoing it reopens the bill or invoice.
  • A payment over several bills or invoices is refused with
    422 match_is_part_of_payment: reverse the whole payment with
    reconciliationMatch.unmatch and the match id the refusal names.
  • A leg of a transfer between two accounts is undone only with
    transfer.unmatch (preview, then commit) and the transfer id the 409 lists
    in booked_transaction_ids, never with bankTransaction.booking.undo, which
    has no preview. The transfer's bank lines go back to To review, and a
    counterpart line Cybooks created for it is deleted.
  • A booking only Cybooks can undo: the 409 bank_line_already_booked names no
    undo operation (undo_operation_id is empty), and the user undoes it in
    Cybooks (Reconcile, Done tab).

booked_transaction_ids on a bank line

Each bank line now carries booked_transaction_ids: every booking row on the
line, either side, newest payment first, as
GET /v1/bank-transactions/{id}/booked-transactions lists them. That includes
rows an undo does not take on their own, such as a fee line's booking or the
other side of a transfer: read the bookings before you undo one.

Short answers to writes: Prefer: return=minimal

An agent that books many lines rarely needs the whole line back. These six
writes take the Prefer: return=minimal header (RFC 7240).
Over MCP, cybooks_categorize_bank_transaction is listed; the others are
reached through cybooks_search_capabilities and run with
cybooks_write_capability.

EndpointMCP tool
POST /v1/bank-transactions/{id}/categorizecybooks_categorize_bank_transaction
POST /v1/bank-transactions/{id}/book-incomingcybooks_book_incoming_bank_transaction
POST /v1/bank-transactions/{id}/book-outgoingcybooks_book_outgoing_bank_transaction
POST /v1/booked-transactionscybooks_create_manual_booked_transaction
POST /v1/bank-transactions/{id}/booked-transactions/{bookingId}/undocybooks_undo_bank_transaction_booking
POST /v1/bank-transactions/{id}/booked-transactions/{bookingId}/unreconcilecybooks_unreconcile_bank_transaction_booking

With the header, data carries only id, version, etag,
reconciliation_state and booked_transaction_ids, meta is unchanged, and
the response carries Preference-Applied: return=minimal. Each of these
writes answers with Vary: Prefer, with or without the header. Over MCP, pass
the argument return: "minimal".

Send the line's ETag in Cybooks-If-Match, never the standard If-Match
(see Authentication).

POST /v1/bank-transactions/9c1d.../categorize
Idempotency-Key: 6f1e...
Cybooks-If-Match: "3f9c1a7d0b2e4c51-v4"
Prefer: return=minimal
{
  "data": {
    "id": "9c1d...",
    "version": 5,
    "etag": "\"3f9c1a7d0b2e4c51-v5\"",
    "reconciliation_state": "reconciled",
    "booked_transaction_ids": ["b07a..."]
  }
}
  • A booking write (book-incoming, book-outgoing, POST /v1/booked-transactions)
    answers with the booking: its id, version and etag, its
    reconciliation.state, and its own id in booked_transaction_ids. On
    book-incoming and book-outgoing the bank line's new version stays in
    meta.bank_transaction_version. To undo or
    unreconcile next, send the line's ETag; read the line
    (GET /v1/bank-transactions/{id}) if you no longer hold it.
  • A replay of the same Idempotency-Key is answered by the Prefer header the
    replay sends: Cybooks stores the full answer, and Prefer is not part of the
    request fingerprint. The same key with and without the header is the same
    request.
  • Every other endpoint ignores the header and answers in full without
    Preference-Applied; the bulk exclude, include, delete and categorize
    commits are among them. Over MCP, every other tool refuses the return argument.

Money back from a supplier

Money in from a supplier is a refund, and categorize refuses it with
422 supplier_refund_needs_vendor_credit. Refund a vendor credit against the
line.

Look first: vendorCredit.index with filter[contact_id] = the supplier. If
an approved vendor credit (status open or part-paid) has at least the
line's amount in unapplied_amount, go to step 3 with it. Only when there is
none:

  1. vendorCredit.store: a vendor credit for the supplier, with the account
    and VAT rule of the original charge.
  2. vendorCredit.approve.
  3. vendorCredit.refund.preview with bank_transaction_id = the line. The
    line's account, amount and date are used, so payment_account_id,
    amount and payment_date may be left out. It returns a
    confirmation_token.
  4. vendorCredit.refund.create with the same body, the token,
    the same Idempotency-Key as the preview and the vendor credit's ETag. It books
    this line; no second line is created.

The refusal codes are in Settling bills from bank lines.

Money back to a customer

Money out to a customer is a refund, and categorize refuses it with
422 customer_refund_needs_credit_note. A line that is already on the
account cannot be booked as a customer refund through the API yet, and
Cybooks does not offer that booking to every company yet: leave the line
unbooked and tell the user.

A refund to a customer belongs on a credit note. Record one only when the
user asks for it, and look first: creditNote.index with
filter[contact_id] = the customer and filter[status]=open; when an
approved credit note has the line's amount in unapplied_amount, create
nothing. Otherwise creditNote.store with the account and VAT rule of the
original sale, then creditNote.approve: approving posts to the ledger, and
the line stays to review until the user settles it in Cybooks.

Do not also record the refund with creditNote.refund.preview /
creditNote.refund.create. They take payment_account_id, amount and
payment_date and always record a new outgoing payment: they never take an
existing line and refuse a statement-backed account. Run next to a line
already on the account, they count the refund twice and close the credit
note, so the line can no longer be booked against it. Use them only for a
refund that is on no account yet, on an account that is not statement-backed,
with the preview's confirmation_token, the same Idempotency-Key and the
credit note's ETag. Booking an imported line to a credit note is not in the
API yet.

Exclude, include or delete lines in bulk

Each bulk action takes up to 100 line ids and is two calls with the same body
and the same Idempotency-Key:

  1. The preview (….preview) writes nothing. It returns one result per id
    (eligible, or the reason the line is left alone) and a
    confirmation_token, valid for 5 minutes.
  2. The commit, with the same ids, the token and
    the same Idempotency-Key as the preview: the token is bound to that
    key, and a commit with another key is refused with 422. It acts on the lines the
    preview marked eligible and returns every other id with its preview
    status. A line that changed since the preview answers 412: preview again
    with a new key.
  • Exclude (bankTransaction.bulkExclude) takes lines out of
    reconciliation. Only the flag changes: no booking or journal entry is made
    or removed. A line already excluded is already_excluded; a line Cybooks
    protects, for example one that is reconciled, matched, booked, documented
    or edited by a person, is protected with its reasons.
  • Include (bankTransaction.bulkInclude) puts excluded lines back, the
    inverse of exclude. A line that is not excluded is not_excluded.
  • Delete (bankTransaction.bulkDelete) soft-deletes lines. A deleted
    line leaves the account balance, and a deleted feed line is never imported
    again. The account-type rule and the shared protections are listed in the
    bankTransaction.bulkDelete.preview reference.

Exclude, include and delete only what the user asked for.

The account's unreconciled_transaction_count

unreconciled_transaction_count on GET /v1/payment-accounts and
GET /v1/payment-accounts/{id} leaves out excluded lines. It now equals the
number of lines GET /v1/bank-transactions lists with
filter[payment_account_id] and filter[reconciliation_state]=unreconciled.
It used to count excluded lines that had no booking as well.

Bulk categorize

Bulk categorize books up to 50 bank lines in one preview and one commit, each
line with the body bankTransaction.categorize takes. A year of about 1,600
lines takes 32 preview and commit pairs instead of 1,600 calls. Each line is
still booked on its own, exactly as a single categorize books it: what one line
refuses never stops the others.

It takes three steps: a read-only preview, a commit that answers 202 at once,
and a status read you poll while a job books the lines.

EndpointOperationAnswers
POST /v1/bank-transactions/bulk-categorize/previewbankTransaction.bulkCategorize.preview200: every item ready (with its journal) or refused; totals; confirmation_token
POST /v1/bank-transactions/bulk-categorizebankTransaction.bulkCategorize202: operation_id, status queued, total
GET /v1/bank-transactions/bulk-categorize/operations/{operationId}bankTransaction.bulkCategorize.status200: the operation's status and every line's outcome

All three need the bank-transactions:action OAuth scope and the
update_bank_accounts permission. Over MCP they are capabilities with the same
operation IDs: find them with cybooks_search_capabilities "bulk categorize",
run the preview and the status read with cybooks_read_capability and the
commit with cybooks_write_capability.

1. Preview

POST /v1/bank-transactions/bulk-categorize/preview
Idempotency-Key: 0b6f3c2e-bulk-2026-10

{
  "items": [
    {
      "bank_transaction_id": "9d1c…",
      "counterparty_id": "4a77…",
      "account_code": "6100",
      "tax_code": "G",
      "memo": "Bank charges October"
    }
  ]
}
  • items: 1 to 50 objects, each bank line once. Each item is the
    bankTransaction.categorize body (counterparty_id, account_id or
    account_code, tax_rule_id or tax_code, memo, optional tags) plus
    the line's bank_transaction_id.
  • An empty items, one that is not a list or more than 50 items refuses the
    whole request with 422 keyed items; a wrong item shape or a line named
    twice, keyed items.N.<field>.
  • The preview writes nothing and locks nothing. Every item answers on its own,
    with its index:
    • ready, with the journal the booking would post (per line the account,
      debit and credit in the company's currency, the line currency's
      amounts and the tax rule; for a line in another currency the
      exchange_rate used), or
    • refused, with http_status, code, message and fields exactly as
      bankTransaction.categorize refuses that line: bank_line_already_booked,
      bank_line_held_by_booking, bank_line_excluded,
      supplier_refund_needs_vendor_credit, tags_need_plan, a closed period,
      a salary line you may not see (403) and so on.
  • totals counts the ready and refused items and sums the ready items'
    debits and credits.
  • When any item is ready, confirmation_token binds the ready items for
    5 minutes to you, your client, the Idempotency-Key and the body. Refused
    items are never booked: fix them and send them again in a later preview.

2. Commit

Send the same items with the same Idempotency-Key, plus the token:

POST /v1/bank-transactions/bulk-categorize
Idempotency-Key: 0b6f3c2e-bulk-2026-10

{
  "items": [ … the same items … ],
  "confirmation_token": "…"
}
HTTP/1.1 202 Accepted

{ "data": { "operation_id": "5f0e…", "status": "queued", "total": 48 } }

total is the number of ready lines the job will book. Nothing is booked
inside the request.

  • Idempotency-Key is required. A replay with the same key and body answers
    the stored 202 and starts no second operation.
  • A body that differs from the preview's answers 412; an expired or
    tampered token 422; a token already used 409
    confirmation_already_claimed.
  • At most 3 bulk categorize operations per person and client may be queued or
    running at once. A fourth answers 409 bulk_categorize_busy: read one
    until it ends, then commit again with the same key and token, or preview
    again if the token expired (it lives 5 minutes).
  • An AI agent that holds a work lease on the lines (work.claim) sends it as
    the top-level lease_id argument over MCP, next to body, as on every
    write; the body takes no lease_id. The
    commit keeps that lease for the job, which checks the leases again before
    every line.

3. Status

GET /v1/bank-transactions/bulk-categorize/operations/5f0e…

{
  "data": {
    "operation_id": "5f0e…",
    "status": "succeeded",
    "total": 48, "booked": 46, "refused": 2, "failed": 0, "pending": 0,
    "items": [
      { "bank_transaction_id": "9d1c…", "outcome": "booked", "booked_transaction_ids": ["c3a1…"], "code": null, "message": null },
      { "bank_transaction_id": "a802…", "outcome": "refused", "booked_transaction_ids": [], "code": "bank_line_already_booked", "message": "…" }
    ]
  }
}

status is queued, running or succeeded (every line has an outcome,
refused ones included). Poll every few seconds until it is succeeded; 50
lines take well under a minute. A long run may hand the operation back to
queued for a moment before it goes on. Only your own operations
through the same client are readable: any other id answers 404. The generic
GET /v1/operations/{id} shows the same counts and items under result,
never the line bodies you sent.

Each line's outcome:

outcomeMeaning
bookedBooked as bankTransaction.categorize books it; booked_transaction_ids names the bookings.
refusedNot booked; code and message say why (below). Nothing of the line was written.
failedNot booked because of an unexpected error (bulk_categorize_item_failed). It is reported to us; categorize the line on its own or preview it again.
pendingThe job has not reached the line yet.

Refusals while the job books

The job checks every line again just before it books it, in its own
transaction, so a line that changed after the preview is refused, never booked
on stale facts:

codeWhy
any code of bankTransaction.categorizeThe line refuses now what the single categorize would refuse: booked by someone else meanwhile (bank_line_already_booked), excluded, in a period locked since the preview, and so on.
changed_since_previewThe line, its eligibility or the journal it would post changed since the preview, a moved exchange rate included. Preview it again.
journal_mismatchThe posted journal differed from the preview's; nothing was booked. Preview it again.
journal_unbalancedThe posted journal did not balance; nothing was booked. Preview it again.
needs_permissionYou lost update_bank_accounts while the job ran, or the channel you committed on can no longer be checked: every line left ends with this code.
subscription_expiredThe company's subscription expired while the job ran: every line left ends with this code.
bulk_categorize_pausedBulk categorize was switched off while the job ran: every line left ends with this code.
agents_stopped, run_pausedFor an AI agent: the company's STOP or the run's pause, checked before every line. Every line left ends with the code.
leased_by_other_agentFor an AI agent: another agent holds a work lease on the line or its counterparty.

Rate limits and the daily cap

A bulk preview and a bulk commit are one request each toward the api-v1
rate limit and the API key's daily cap, whatever the number of lines: the cap
counts calls, not lines. Each status read is one request.

Switched off

Operators can switch bulk categorize off. While it is off the preview and the
commit answer 503 with Retry-After: 30; categorize the lines one by one with
bankTransaction.categorize meanwhile. A job that is running stops before its
next line, which ends bulk_categorize_paused.

ETags and *

Send the ETag of your last read of the line. * writes whatever the current
version is, without checking that nobody changed the line since: use the ETag
when you have read the line. Categorize and undo accept *; the operations
that refuse it are listed in Authentication.


Did this page help you?