Bills
Bills
A bill is a purchase document from a supplier. Every bill a company has in
Cybooks is on GET /v1/bills (cybooks_list_bills over MCP) and
GET /v1/bills/{id} (cybooks_get_bill), except opening balances, archived
drafts and the bills an expense claim owns.
Prices, VAT and the bill detail
tax_type and unit_price_basis are gross when prices include VAT, and
net when they exclude it. Each line's unit_price uses that basis, before
its discount. The read price is consistent with the stored line amount,
including on extracted drafts that stored a net price next to a gross amount.
For example, a fee of 14.28 including 19% VAT reads as unit_price: "14.2800",
vat_amount: "2.28" and unit_price_basis: "gross".
To round-trip a draft through bill.update, copy its tax_type and the
editable line fields: id, quantity, unit_price, discount,
discount_type, order, description, tag_dimension_id,
ip_box_category, ip_box_percentage, ip_box_asset_id, and the account and
tax rule. line_items replaces the lines: a description, tag_dimension_id
or ip_box_* field left out of a line is cleared. product_id,
adds_to_stock_cost and serials left out keep what the line holds.
Use account_id for the returned chart_of_account_id, or use account_code;
use tax_rule_id or tax_code. Do not send read-only amount, totals or
chart_of_account_id. Unchanged prices, quantities and discounts,
compared at the four decimals the read returns,
preserve the stored line amounts and quantities even where a four-decimal value cannot
represent them exactly, on either tax basis. A negative price is accepted only on
an existing line at its stored price, quantity and discount (a Rounding line).
Changed pricing is recalculated. An update that omits
the lines also keeps their entered amounts. If the currency, tax basis, line
amounts, tax rules and stock classification are unchanged, valid stored header totals keep their
printed rounding difference from the line sum; on a bill with an import VAT line
only up to one cent, the most approval accepts. A financial change recalculates
the totals; this does not relax the posting consistency checks.
Every line also returns tax_rule_name, alongside tax_rule_id, and
vat_amount in the bill currency, using the line's tax rule and the bill's
net/gross basis. This is line VAT before bill-level input-VAT caps or
entitlement adjustments; use the VAT return and journals for claimable VAT.
GET /v1/bills/{id} additionally returns:
attachments: fileid,name,mime_type,sizeand
content_operation_id: "bill.attachment". Pass that id asattachmentId
with the bill'sidto read the file;query.include_content: truerequests
small files inline (see attachment content below). Storage paths and signed
links are not embedded in the bill detail.payments(included only with theview_bank_accountspermission, as on
the bill payment endpoints): active booked settlements, oldest first, with
booked_transaction_id(the booking, not abill.payment.showid),
payment_date,amountandcurrency_id(what it settled on this bill, in
the bill's currency; null when no stored figure says),
bank_amountandbank_currency_id(the booking's figure in the bank's
currency),bank_amount_shared(true when one bank line in another currency
paid several documents:bank_amountis then the whole line, not this bill's share),
payment_account_transaction_id(the bank line id, or null) and
payment_account(id,name). A settlement from another currency stops at
what bookings settled in total (the bill less applied supplier credits and what is still unpaid), taken in booking order. The figures are worked out from the bookings that stand today: after a reversal and a rebooking, the split between bookings can differ from what each one moved at the time, though the total does not. These include settlements made in the app
or by matching a bank line, not only payments made through the public API.
Deleted bookings and reversal-trail copies are excluded. A related party's
personal account, bank-line identity and bank figures remain private;amount
stays, because it is what the bill settled.journal_entry_ids: the bill's own journal entries, including reversal
history; a draft with no posting returns an empty array.
These detail collections are not embedded in the bill list. A paid-already
mark or an outstanding bank file remains in being_paid until it is settled;
it is not a booked payment.
Two ways a bill is settled
Each bill carries a flow.
flow | What it is | How it is settled |
|---|---|---|
payable | A bill to pay later. It posts to accounts payable when it is approved. | Record a payment (POST /v1/bills/{id}/payments), or match the bank line that paid it. |
expense | A bill recorded as paid from an account: a receipt from the document inbox saved with "Paid from: Wise EUR", for example. | Match the bank line that paid it. |
An expense-flow bill names the account in paid_from:
{
"id": "01a0e699-9a2f-72e0-9d4a-614e6af17e8d",
"status": "open",
"flow": "expense",
"paid_from": {
"payment_account_id": "9dddd6d8-…",
"name": "WISE EUR"
},
"unpaid_amount": "105.00",
"settlement": "none"
}paid_from is null on a payable bill. It is also null when the bill was
paid by a related party (a director's personal card, say): a personal account
is never shown on the API.
An approved expense-flow bill whose bank line is not matched yet is open,
with its full amount in unpaid_amount. The expense and the payable are
already in the books. Do not book the bank line as a new expense, and do not
upload the receipt again: match the line to this bill instead.
To list them: GET /v1/bills?filter[flow]=expense (or filter[flow]=payable
for the rest).
Filter the bill list
GET /v1/bills takes filter[id], filter[status], filter[vendor_id],
filter[cost_centre_id], filter[flow], filter[search] and
filter[updated_since]. Over MCP, cybooks_list_bills takes the same names
under query.filter. An unknown filter is refused with a 422 that names it.
filter[status] takes draft, open, paid, part-paid or voided, in
lower case; any other value is refused with a 422 that lists them.
filter[cost_centre_id]=<id> lists the bills booked to one cost centre: the
cost_centre_id each bill carries (include=cost_centre adds its name). It
matches the cost centre set on the bill itself.
Match an expense-flow bill to its bank line
- Find the bank line:
GET /v1/bank-transactions(cybooks_list_bank_transactions). - List what it can be matched to:
GET /v1/bank-transactions/{id}/reconciliation-candidates
(cybooks_list_reconciliation_candidates). The bill is a candidate of
type: "bill". Passqwith the supplier name or the bill number to
search past the first page, orfilter[bill_id]with one bill's id to
read that bill's candidate alone, however many other bills the line
matches: an empty list means the bill is no candidate of this line.
Within oneconfidencethe candidates come best match first. - Preview the match:
POST /v1/bank-transactions/{id}/reconciliation-matches/previewwith
{"candidate_type": "bill", "candidate_id": "<bill id>"}
(cybooks_preview_reconciliation_match). It returns the ledger effect and
aconfirmation_token. - Commit it with the same body plus the
confirmation_token
(cybooks_create_reconciliation_match).
The bill becomes paid.
A bill in another currency than its bank line (a USD bill paid from a EUR
account) is matched in one step when the bank line also carries the amount in
the bill's currency, as card and Wise lines do: the candidate says
confirmable: true, and the exchange difference posts with the match, as it
does in the app. A candidate with confirmable: false and
requires_manual_fx: true needs a person to confirm the rate: match it in
Cybooks.
A bill candidate also says proposable_by_agents (null on a VAT payable): false while the bill
waits for approval or sits in a bank payment file. An agent proposes only a
candidate with proposable_by_agents: true; the match itself checks the same
rule again.
To see how a supplier's earlier lines were reconciled, list them with
GET /v1/bank-transactions?filter[counterparty_id]=<vendor id>&filter[reconciliation_state]=reconciled
(newest first). counterparty_id is the counterparty.id a bank line shows.
What you can do with an expense-flow bill
| Action | Expense-flow bill |
|---|---|
| Read, list, PDF, attachments | Yes |
| Match its bank line | Yes |
Correct an approved bill (bill.correct) | Yes, when it was paid from a company account that still exists; the Paid from account stays. A bill a related party paid, or one whose account was removed, answers bill_expense_flow_not_supported: correct it in Cybooks. |
| Void an open, unpaid bill | Yes, when it was paid from a company account. A bill a related party paid answers bill_void_payment_account. |
| Approve a draft | Yes. A draft a related party paid answers bill_expense_flow_not_supported: approving it also records the related party's payment, which only Cybooks does. |
Edit a draft (PATCH /v1/bills/{id}) | Yes, when it was paid from a company account that still exists: the Paid from account (and its rebill customer) stays, and the edit keeps the currency and the gross total, because the account paid that amount and its bank line is matched by it. Lines, accounts, tax rules, dates and text may change; a change of the gross total or the currency answers 422 bill_expense_flow_total_changed. An edit that sends no line_items (and keeps tax_type) keeps the stored totals and line amounts, so a total as printed stays. The automatic bank match also looks at the document date and the supplier: changing either, as on the bill page, leaves the line to match by hand. A draft a related party paid, or one whose account was removed, answers bill_expense_flow_not_supported: edit it in Cybooks (a bill created again over the API is a payable to the supplier: for a draft a related party paid, that leaves out the related party's payment). |
Record a payment (/payments) | No: bill_expense_flow_not_supported. Match the bank line instead, so the line is not booked twice. |
| Apply or remove a vendor credit | No: bill_expense_flow_not_supported. Do it in Cybooks. |
| Archive, restore or delete a draft | Yes |
Every refusal is a 409 with the code in error.code and at the start of
error.message, never a 404. A 404 on a bill id means there is no such
bill in the company.
Delete or void
Only a draft is deleted (POST /v1/bills/{id}/delete,
cybooks_bill_destroy). A draft has posted nothing, so nothing is left behind.
An approved, paid or voided bill has posted to the ledger. It is never
deleted, in the app or over the API (bill_delete_not_draft). Void it
instead (POST /v1/bills/{id}/void, cybooks_void_bill): the void posts a
reversing entry dated in the first open period, and the original posting
stays, so the trail is whole. A void can be reversed
(POST /v1/bills/{id}/reverse).
The day the void's reversal posts on
By default the reversal is dated today, or the first open day when a lock
runs past today. A bill dated in one VAT quarter and voided in the next
then sits in the first quarter's profit and loss with its reversal in the
second. Send reversal_date (YYYY-MM-DD) on the void to date the reversal
yourself, for example on the bill's own date, so the bill and its reversal
net to zero in the same period:
POST /v1/bills/{id}/void
{ "reason": "Entered twice", "reversal_date": "2026-09-02" }The day must be on or after the bill's date (and after each of its posting
entries), not after today (Nicosia), and in an open period that no filed VAT
or OSS return covers. Otherwise the void writes nothing and answers 422
with the code in error.code and reversal_date in error.fields. A bill
entry already in a locked period still reverses inside its own financial
year.
The VAT return does not depend on the reversal's date: a voided bill is left
out of every return, in its own period and the reversal's. The date decides
where the bill and its reversal sit in the ledger and the profit and loss.
POST /v1/bills/{id}/void/preview (cybooks_bill_void_preview) shows what a
void would post, with or without reversal_date, and writes nothing: state
(ready, manual when a void needs a manual adjustment, voided once it is
voided), original_date, reversal_date, the reversing lines and the
bill's etag to send as Cybooks-If-Match (or the standard If-Match) on the void. It refuses what the void
would refuse, by the same codes. It issues no token: bill.void keeps its
contract.
For a void that posts (state ready), vat_boxes lists the VAT return
boxes the void moves: per box and VAT period, what the bill puts in that box
now (from), what stays (to, always 0.00) and the change, in euros.
The figures are the VAT return's own, read for the bill's posting entries:
boxes 1, 2 and 4 carry VAT and the others the net, so a reverse-charge bill
shows its self-assessed VAT in boxes 1 and 4 beside its net in boxes 6, 7
and, for EU services, 11B. The period is the one the bill's posting entry
sits in (period_start, period_end and vat_return_status: the VAT
return that covers it, or null when none does). A completed status means
the void changes a return already filed: correct it in a later return. When
a change of filing frequency left two returns over the same dates, the bill
shows under each: do not add those rows up. The
reversal_date never moves a box: the return
leaves a voided bill out of its own period, so the reversal's period stays as
it is. A bill no box counts (exempt, for example) answers [], and so do
manual (the void writes nothing) and voided. The return rounds boxes 6 to
11 to whole euros on its total, so its own figure can differ from change by
the rounding. vat_boxes is null when the VAT return cannot read the bill
(a company whose base currency is not the euro, on an entry without its euro
filing rate); the rest of the preview is still served.
"vat_boxes": [
{ "box": "box-4", "period_start": "2026-07-01", "period_end": "2026-09-30",
"vat_return_status": "draft", "from": "19.00", "to": "0.00", "change": "-19.00" },
{ "box": "box-7", "period_start": "2026-07-01", "period_end": "2026-09-30",
"vat_return_status": "draft", "from": "100.00", "to": "0.00", "change": "-100.00" }
]Move a void's reversal to another day
A bill already voided with its reversal on the wrong day is fixed with a
preview and a commit. Nothing is edited in place: for each void entry the
commit posts that entry's inverse on the entry's own date, so that period
nets to zero again, and a new reversal of the bill on reversal_date. The
bill stays voided, with its reason and time, and can still be reopened with
bill.reverse.
POST /v1/bills/{id}/void/redate/previewwith anIdempotency-Keyand
{ "reversal_date": "2026-09-02" }(cybooks_bill_void_reversal_redate_preview).
It returnsmoves[](each void entry with itsfromandtodate),
current_reversal_date, the reversinglines, the bill'setagand a
confirmation_token.POST /v1/bills/{id}/void/redatewith the same key, the same
reversal_date, theconfirmation_tokenandCybooks-If-Match: <etag>
(cybooks_bill_void_reversal_redate). A change since the preview answers
412: preview again. Anotherreversal_dateis checked again first, so a
day the move refuses answers that refusal's code (422or409), and any
other day412.
Both need the bills:action scope with update_bills and void_bills. The
new day is checked as a void's reversal_date is, and the void entry's own
day must be open too, because its inverse is posted there.
A VAT period filed outside Cybooks (in TFA directly) is not closed in
Cybooks until its return is recorded or a lock is set. Moving a reversal into
such a period is allowed while it is open. When the bill was entered after
that return was filed, so the filed figures never held it, moving the
reversal onto the bill's own date leaves the period exactly as it was filed:
set the lock or record the return afterwards, not before. When the filed
return did include the bill (a duplicate already in the export), Cybooks
leaves the voided bill out of that period whatever the reversal's date, so
the over-claimed VAT needs a correction in a later return.
Preview a new bill
POST /v1/bills/preview (cybooks_bill_store_preview over MCP) takes the body
POST /v1/bills takes and answers with the draft it would save, writing
nothing. No confirmation token: create the bill with POST /v1/bills and the
same body.
vendornames the supplier (id,name); it is null for a supplier not
created yet.due_dateanddescriptionare the bill's own.- Each line shows its account, its tax rule (
import_vatis true for an
import VAT rule), the quantity, unit price and entered amount, and the net,
VAT and gross the bill carries. An import VAT line shows the VAT control
account it posts to, whatever account the request named.totalsare the
bill's own totals. exchange_rate.statusisbase_currency(no rate),document_date(the
ECB rate of the document date, or Cybooks' stored ECB rate of that date,
named insource) orat_approval: no ECB rate can be read now, so the
draft is saved without one and approval takes the document date's rate.
Cybooks never estimates a rate, andexchange_rateis never taken from the
request.period_stateisopen,locked(a period lock or the hard lock covers
the document date) orfiled(a filed VAT return covers it).vendor_idmay be left out for a supplier not created yet: send
supplier_nameinstead, and optionallysupplier_vat_idand
supplier_country_id: the supplier's VAT number and country, used only by
the zero-rate check Cybooks AI runs in the app's chat, and never saved.
supplier_legal_name,supplier_registration_number,supplier_emailand
supplier_phonemay be sent too: in Cybooks AI's chat they feed the same
duplicate-supplier check that creating the supplier runs, and are never
saved. The supplier's own checks run onPOST /v1/vendors.
Every other check ofPOST /v1/billsapplies, with the same refusals.- In Cybooks AI's chat, the preview of a bill for a supplier not created yet
is refused with409 vendor_possible_duplicatewhen Cybooks already has
one like it (error.fields.vendor_ids), and a bill from a supplier with a
document number another of its bills (not voided) already has is refused
with409 bill_document_number_used(error.fields.bill_id).POST /v1/billsrefuses it the same way there.
Currency
currency_id is the company's own currency unless the plan includes
multi-currency: another currency is refused with 422, error.code
validation_failed and the reason in error.fields.currency_id, on
POST /v1/bills, its preview and PATCH /v1/bills/{id}, over REST, MCP and
Cybooks AI alike. A bill already saved in another currency keeps it:
PATCH may send its own currency_id back unchanged, and only a change to
another currency is refused.
Files attached in Cybooks AI
attachment_ids (on POST /v1/bills and its preview, up to 5) names files
the caller attached in a Cybooks AI conversation of their own, such as the
supplier's invoice PDF. POST /v1/bills copies each onto the new bill as its
document; the conversation keeps its file. The caller needs access to Cybooks
AI (403 cybooks_ai_access_required); an id that is not such a file of the
caller is refused with 404 attachment_not_found. The preview lists the
files as attachments (id, name).
The account on each line
Every bill line posts its amount to an account: an expense (such as Office
expenses), cost of sales, or an asset for something the company buys to keep
(such as Computer equipment). Name it on the line in one of two ways:
| Field | What it is |
|---|---|
account_id | The account's id from the chart of accounts list (GET /v1/accounting/chart-of-accounts, cybooks_list_chart_of_accounts). Every account has one. |
account_code | The account's code, such as 6210. |
Codes are optional in a chart of accounts: a chart imported or built without
them has "code": null on most of its accounts, and then only account_id
can name the account. Send account_id whenever you have it. Never post to
another account with a code and move the line later.
POST /v1/bills
{
"vendor_id": "…",
"currency_id": "…",
"tax_type": "net",
"date_of_document": "2026-10-01",
"line_items": [
{
"description": "Property management, Q4 2026",
"quantity": 1,
"unit_price": 128.45,
"account_id": "397",
"tax_code": "T",
"order": 0
}
]
}To list the accounts the Cybooks bill editor offers on a line, filter the
chart of accounts by the screen:
GET /v1/accounting/chart-of-accounts?filter[usable_for]=bill_line (over MCP,
cybooks_list_chart_of_accounts with {"query": {"filter": {"usable_for": "bill_line"}}}).
The list has the screen's own filter: the unarchived postable expense and
asset accounts. It does not apply the rules below, so the line is still
refused for a control account it lists, such as accounts receivable or a bank
account's ledger. filter[usable_for] also takes:
bank_line: the accounts the To do card offers as a bank line's category
(income, expense, asset, liability and equity, without the cash and cash
equivalents, accounts receivable, accounts payable and VAT control
accounts). The ledgers of the company's own payment accounts (each bank,
card or cash account's ledger) are listed, as the card lists them, but
categorizing a bank line to its own payment account's ledger is refused
with 422: a move between your own accounts is a transfer.journal_line: the accounts the manual journal screen offers on a line,
every unarchived postable income, equity, liability, asset and expense
account. That includes the receivable, payable, bank and card ledgers the
screen lists.opening_balance: the accounts a ledger opening balance accepts, of every
type: active, a leaf (no sub-accounts) at depth 2, and not the foreign VAT
payable group. Every account also carriesdepth(0 an account type, 1 a
detail type, 2 a postable account) andis_leaf.
The same list takes filter[type]: one account type (filter[type]=equity)
or several (filter[type][]=income&filter[type][]=equity), from asset,
liability, equity, income, expense, cogs and uncategorized. It
also takes filter[search]: the whole phrase, as typed, matched as one piece
of the name, the code or the description (% and _ match themselves). A
usable_for list never includes an archived account, whatever
include_archived says.
account_idmust name an active expense, cost of sales or asset
account of the company: not archived, not an account type or detail type
heading, and not a control account (accounts receivable, accounts payable,
VAT, or the ledger of a bank account). Anything else is refused with
422 bill_line_account_unavailable, naming the line inerror.fields. The
id is a string of digits, as the chart of accounts list returns it (over
REST a JSON number is accepted too).- A line you send back with its
idmay keep the account it already has
(itschart_of_account_idasaccount_id) while that account is active,
whatever its type. - If you send both
account_idandaccount_code, they must name the same
account. account_codekeeps working as before. Each line needs one of the two.- The bill you get back shows each line's account as
chart_of_account_id
(the same id, as a string) andaccount_code(nullwhen the account has
no code). - An update that sends
line_items(PATCH /v1/bills/{id},
cybooks_update_bill) replaces every line: send each line with itsid
and its account (itschart_of_account_idasaccount_id). An update that
sends noline_itemskeeps every line on its account and tax rule. - To change the account of an approved bill, correct it
(Correcting approved bills), which takes
account_idtoo.
Inbox documents
A supplier invoice or receipt read into the document inbox is a document
extraction until it is converted to a bill. Its lines take the same two
fields: PATCH /v1/document-extractions/{id}
(cybooks_update_document_extraction) with line_items, each line with its
id, its account (account_id or account_code) and its tax_code. The
rules above apply, and a refused account_id answers
422 document_extraction_line_account_unavailable and saves nothing. Like a
bill update, line_items replaces every line.
Converting the document (POST /v1/document-extractions/{id}/convert-to-bill,
cybooks_convert_document_extraction_to_bill) gives each bill line its inbox
line's account. A document with a line that has no account is not converted:
409 document_extraction_incomplete lists the line in error.fields.missing.
Expense claims
An expense claim is money an employee or a director spent for the company, to
be paid back; approving it makes a bill. Its lines name the account the same
way, and their tax rule by id too: POST /v1/expense-claims and
PATCH /v1/expense-claims/{id} (cybooks_create_expense_claim,
cybooks_update_expense_claim).
| Field | What it is |
|---|---|
account_id | The account's id from the chart of accounts list. |
account_code | The account's code. Each line needs one of the two. |
tax_rule_id | The tax rule's id from the tax rules list (GET /v1/accounting/tax-rules, cybooks_list_tax_rules). Tax rules made in Cybooks have no code. |
tax_code | The tax rule's code. Each line needs one of the two. |
POST /v1/expense-claims
{
"claimant_type": "employee",
"claimant_id": "…",
"merchant_name": "Electricity Authority",
"spent_on": "2026-10-02",
"tax_type": "gross",
"currency_id": "…",
"line_items": [
{
"description": "Electricity, September",
"amount": "84.20",
"account_id": "245",
"tax_rule_id": "…",
"order": 0
}
]
}account_idmust name an active expense account of the company: not
archived, not a heading, not a control account (accounts receivable or
payable, VAT) or the ledger of a bank account. When the company limits the
accounts claims may use (Settings › Expense claims › Accounts), it must be
one of them instead, of any type:GET /v1/expense-claims/settings
(cybooks_get_expense_claim_settings) lists the ones a line can name in
allowed_account_ids(andmileage_allowed_account_idsfor mileage claims,
which always post to an expense account). Anything else is refused with
422 expense_claim_line_account_unavailable, naming the line in
error.fields, and nothing is saved.account_codesent alone keeps its earlier rule: an active expense account
(the company's allowed accounts still apply when the claim is saved). Sent
withaccount_id, the id decides and the code only has to name the same
account.tax_rule_idmust name a purchase or no-VAT tax rule of the company, else
422 expense_claim_line_tax_rule_unavailable. The tax rate always comes from
the tax rule.- Sent together,
account_idandaccount_code(ortax_rule_idand
tax_code) must name the same record. - The claim you get back shows each line's
chart_of_account_idand
tax_rule_id(strings) next toaccount_codeandtax_code(nullwhen
there is no code). - An update that sends
line_itemsreplaces every line: send each with its
id, itschart_of_account_idasaccount_idand itstax_rule_id. A
line sent with itsidkeeps the account and tax rule it already has, even
one this rule would not offer today, while the account is active and
unarchived and the company still allows it on expense claims. An update
withoutline_itemskeeps every line on its account and tax rule the same
way.
When a claim is refused
POST /v1/expense-claims/{id}/submit, /approve, /decline, /payment,
the update and the delete (cybooks_submit_expense_claim, cybooks_approve_expense_claim
and the others) name every refusal: the code in error.code and at the start
of error.message, what to do in the message, and the field in
error.fields. Nothing is changed.
| Code | Status | When | What to do |
|---|---|---|---|
expense_claim_receipt_required | 422 | Submit: the company asks for a receipt (Settings › Expense claims › Receipt required) and the claim has none. | Attach it in Cybooks or over REST (POST /v1/expense-claims/{id}/receipt-upload-sessions, then complete it; there is no MCP tool for the upload yet), or turn the setting off, then submit again. GET /v1/expense-claims/settings shows receipt_required. Mileage claims never need one. |
expense_claim_status_mismatch | 422 | The claim's status does not allow the action. error.fields.status says which status it is. | Edit takes a draft, submitted or declined claim (or an approved one while its bill is unpaid), submit a draft or declined one, approve a submitted or declined one, decline a submitted or approved one (while its bill is unpaid), delete a draft or declined one. |
expense_claim_period_locked | 422 | Approve: the claim is dated in a locked period. | Approve again with book_in_open_period: true (it books on the first open day, error.fields.next_open_date), or correct spent_on if it is wrong (the claim goes back to draft, so submit it again). |
period_locked | 422 | Another expense-claim write (a payment, or an update or decline of an approved claim) would post in a locked period. | For a payment, use a payment_date after the lock (error.fields.next_open_date); otherwise have the period reopened in Cybooks. |
expense_claim_requirements_missing | 422 | Approve: the company's requirement policy asks for more. error.fields.items lists what. | Add it, then approve again. |
expense_claim_settlement_method_required | 422 | Approve without settlement_method. | Send bank_payout or current_account. |
expense_claim_self_approval | 422 | You are the claimant. | Another person with the approve permission approves it. |
expense_claim_current_account_ineligible, expense_claim_current_account_unavailable | 422 | current_account for someone who is not an active director or shareholder, or whose current account is missing. | Use bank_payout. |
expense_claim_company_account_required, _not_assigned, _unavailable, _statement_backed | 422 | A company-money claim without a usable company account. | Send or fix payment_account_id. |
expense_claim_payment_preparation_stale | 422 | The claim changed while the approval was prepared. | Read it again and retry with the new ETag. |
expense_claim_bill_is_locked, expense_claim_bill_has_payments, expense_claim_bill_has_fixed_assets, expense_claim_bill_requires_manual_adjustment | 422 | The approved claim's bill has payments, credits or a fixed asset, or sits in a closed year. | Sort the bill out in Cybooks first. |
expense_claim_claimant_*, expense_claim_related_party_*, expense_claim_no_linked_employee | 422 | The claimant cannot be used. | Pick one from GET /v1/expense-claims/claimants. |
expense_claim_mileage_*, expense_claim_coa_not_allowed | 422 | A mileage or account rule of the company. | Fix the line the message names. |
expense_claim_awaiting_approval, expense_claim_approved_by_policy, approval_already_decided | 409 | A claims approval policy holds the claim, or someone decided it a moment ago. | Read the claim again. |
expense_claim_pay_permission_required, expense_claim_decline_permission_required, expense_claim_resync_permission_required | 403 | The user behind the token lacks the permission the message names. | Ask someone who has it. |
The tax rule on each line
Name each line's tax rule by tax_code, or by tax_rule_id (the id from
GET /v1/accounting/tax-rules, cybooks_list_tax_rules over MCP). Every rule
has an id; a tax rule made in Cybooks has no code, so only tax_rule_id can
name it. Each line needs one of the two.
tax_rule_idmust name a purchase or no-VAT tax rule of the company,
the same rulestax_codetakes on a bill. Anything else (a sales rule, a
deleted rule, an id the company does not have) is refused with one answer,
422 bill_line_tax_rule_unavailableonline_items.N.tax_rule_id, so it
never tells a missing rule from one that does not fit a bill.- Send both and they must name the same rule, else
422 bill_line_tax_rule_mismatch. - The rate is always the rule's own: Cybooks never takes a rate from the
request. - The bill you get back shows each line's rule as
tax_rule_idand
tax_code(nullwhen the rule has no code). When you replace the lines,
resendtax_rule_idto keep a rule without a code. - To change the tax rule of an approved bill, correct it
(Correcting approved bills).
To list only the rules a bill line takes, filter the list by category:
GET /v1/accounting/tax-rules?filter[category][]=purchases&filter[category][]=no_vat
(over MCP, cybooks_list_tax_rules with
{"query": {"filter": {"category": ["purchases", "no_vat"]}}}). filter[category]
takes one category (filter[category]=no_vat) or several, from sales,
purchases and no_vat; a bank line's money in takes sales and no_vat, its
money out purchases and no_vat, as the To do card offers them. The list also
takes filter[search]: the whole phrase, as typed, matched as one piece of the
rule's name or code (% and _ match themselves). A deleted rule is never listed.
filter[category] and filter[search] are the only filters the tax-rule list takes:
any other filter[...] key is refused with 422 validation_failed, as on the other
v1 lists.
Find the supplier
GET /v1/vendors?filter[search]=Acme (cybooks_list_vendors with
{"query": {"filter": {"search": "Acme"}}}) matches the whole phrase, as typed,
as one piece of what the Cybooks contact picker searches: the name, the first and
last name together, the legal name, the account and supplier numbers, the IBAN,
the VAT ID, the phone, the email and the website (% and _ match themselves).
A VAT ID also matches without its spaces, dots and dashes, on either side, so
CY 10012345X, CY-10012345-X and CY10012345X find each other: search it once,
as printed on the invoice. GET /v1/customers?filter[search]=…
(cybooks_list_customers) searches a customer the same way, with the customer
number, but never the legal name or the IBAN, which the customer row does not
return. Both keep their other filters and list archived contacts only with
filter[status]=archived or all. A search is at most 191 characters.
When Pay bills holds a bill
A bill can be held by Pay bills, Cybooks' bill-payment flow, in two ways.
Every bill says so in being_paid (null when nothing holds it):
being_paid.kind | What holds the bill | How it is freed |
|---|---|---|
bank_file | The bill is in a bank file made in Cybooks, waiting for the bank. | Put it back to To pay in Cybooks. The API does not take a bill out of a bank file. |
paid_already | The bill is marked paid already outside Cybooks (by card, or a transfer made in the bank), waiting for its bank line. A person marks it, or Cybooks does so automatically for bills recorded as paid from a statement-backed account (source: "backfill"). | "Not paid yet": bill.paidAlready.undoPreview, then bill.paidAlready.undo. |
{
"id": "01a0e699-9a2f-72e0-9d4a-614e6af17e8d",
"status": "open",
"flow": "expense",
"being_paid": {
"kind": "paid_already",
"state": "not_seen",
"pay_on": "2026-09-14",
"amount": "105.00",
"currency": "EUR",
"payment_id": "0f3c2b1a-7d6e-4f5a-9b8c-1d2e3f4a5b6c",
"source": "backfill",
"undo_operation_id": "bill.paidAlready.undo"
}
}state is the payment's: waiting for its bank line, not_seen (no line
arrived in the window yet) or seen (its line arrived and waits for a person
in Banking). being_paid is read when the bill is read: marking a bill paid
already or putting it in a bank file in Cybooks, or taking either back there,
does not advance the bill's version or add a change to the feed;
bill.paidAlready.undo does (bill.updated, changed_fields: ["being_paid"]),
and so does a settlement (bill.payment_recorded, bill.paid). While Pay bills holds a bill, a void, a delete or a change of
supplier is refused with 409 bill_in_bank_file or 409 bill_paid_already.
The message names the bank file's day, or the account and day the bill was
marked paid, and what to do next; for a bill paid already,
error.fields.payment_id names the payment.
Take back a paid-already mark ("Not paid yet")
This is what Not paid yet on the bill does in Cybooks: the payment is put
back, the bill is back in To pay, and the bill's history says "Not paid yet".
The mark never reached the ledger, so nothing is booked or reversed and no
period lock applies.
- Preview it:
POST /v1/bills/{id}/paid-already/undo/previewwith an
Idempotency-Keyand no body (cybooks_bill_paid_already_undo_preview).
It returns the payment it takes back, the bill'setagand a
confirmation_token. It writes nothing. - Commit it:
POST /v1/bills/{id}/paid-already/undowith
{"confirmation_token": "…"}, the sameIdempotency-Keyand the
preview'setagasCybooks-If-Match(cybooks_bill_paid_already_undo). It
returns the bill, withbeing_paid: nulland a newETag. - Void the bill with that new
ETagasCybooks-If-Match
(POST /v1/bills/{id}/void,cybooks_void_bill).
Only a mark still waiting for its bank line (waiting or not_seen) is taken
back. It needs the bills:action scope and the update_bills permission; a
support seat cannot do it, as in Cybooks. If the bill or the mark changed
since the preview, the commit answers 412: preview again.
Read the supplier's file
A bill's attachments are the files behind it, usually the supplier's PDF.
GET /v1/bills/{id}/attachments lists them (id, name, type, size) and
GET /v1/bills/{id}/attachments/{attachmentId} reads one. Both need
bills:read and permission to view bills, like the bill itself.
The single read carries download_url, a signed link to the file that works
for five minutes (expires_at) and needs no Authorization header. Read the
attachment again for a fresh link; never store one. The answer is sent with
Cache-Control: no-store and no ETag, so it is never revalidated into a copy
with an expired link.
Add ?include_content=true to also get the file as content_base64. The
limit is on what the base64 text costs in the answer (each / counts twice,
700,000 bytes in all), which is a file of about 500 KB. Otherwise
content_base64 is null and content_unavailable_reason says why:
| Reason | Meaning |
|---|---|
not_requested | include_content was not true. |
too_large | The file is over the limit: download it from download_url. |
inline_budget_exhausted | Earlier files in the same answer used the limit up (an inbox document with several files): download this one. |
file_missing | Storage answered that there is no file at the stored location (404). |
file_unavailable | Storage refused the read (for example a 403) or failed it (a timeout, throttling, a 5xx); the link may still work. |
Over MCP, call cybooks_read_capability with the capability bill.attachment
and the arguments {"id": "<bill id>", "attachmentId": "<attachment id>", "query": {"include_content": true}}. List the ids first with bill.attachments.
Vendor credits (vendorCredit.attachment) and credit notes
(creditNote.attachment) answer the same way.
Avoid booking a bill twice
Before you create a bill from a receipt or a bank line, look for one that is
already there: GET /v1/bills?filter[vendor_id]=<id>, including
filter[flow]=expense, or GET /v1/bills?filter[search]=<number> for the
supplier's invoice number. filter[search] searches as the bills list in
Cybooks does: the supplier's invoice number, the supplier name, the vendor,
the amount, the date and the line text (1 to 191 characters).
Over MCP, cybooks_list_bills takes the same filters under query.filter:
{"query": {"filter": {"search": "0432"}}}. A filter sent at the top level
({"search": "0432"}) is refused with a 422 that names it and says where it
belongs; it is never ignored. Creating a bill with the same supplier, number,
amount and currency as a live bill (within a few days of its date) is refused
with a validation error that names the existing bill.
Error codes
| Code | Status | Meaning |
|---|---|---|
bill_expense_flow_not_supported | 409 | The write is not run on an expense-flow bill over the API. The message says what to do instead. |
bill_expense_flow_total_changed | 422 | An edit of a draft paid from an account would change its gross total or currency. error.fields.line_items names the total to keep (error.fields.currency_id when the currency changed). Send lines that reach it (with tax_type gross, unit_price includes VAT), or change the amount in Cybooks. |
bill_void_payment_account | 409 | The bill was paid by a related party, or is paid or a draft, so it is not voided. Reverse its payment in Cybooks. |
bill_delete_not_draft | 409 | Only a draft is deleted. Void an approved bill. |
bill_delete_has_payments | 409 | The draft has payments or vendor credits. Undo them first. |
bill_line_account_unavailable | 422 | A line's account_id is not an active expense, cost of sales or asset account of this company, or account_id and account_code name different accounts. Returned on create and update. error.fields names the line. |
document_extraction_line_account_unavailable | 422 | The same, on an inbox document's line (PATCH /v1/document-extractions/{id}). Nothing is saved. |
bill_line_tax_rule_unavailable | 422 | A line's tax_rule_id is not a purchase or no-VAT tax rule of this company. Returned on create and update. error.fields names the line. |
bill_line_tax_rule_mismatch | 422 | A line's tax_rule_id and tax_code name different tax rules. Send one of them. |
bill_document_number_used | 409 | Cybooks AI's chat only: a bill from this supplier (not voided) already has this document number. error.fields.bill_id names it. |
vendor_possible_duplicate | 409 | Cybooks AI's chat only: the supplier the bill would create is one Cybooks already has. error.fields.vendor_ids names it. |
attachment_not_found | 404 | An attachment_ids entry is not a file the caller attached in their own Cybooks AI conversation. |
cybooks_ai_access_required | 403 | attachment_ids was sent by a user without access to Cybooks AI. |
expense_claim_line_account_unavailable | 422 | An expense-claim line's account_id is not an account this company's expense claims may use (an active expense account, or one of the accounts the company allows), or account_id and account_code name different accounts. Nothing is saved. |
expense_claim_line_tax_rule_unavailable | 422 | An expense-claim line's tax_rule_id is not a purchase or no-VAT tax rule of this company, or tax_rule_id and tax_code name different tax rules. Nothing is saved. |
expense_claim_receipt_required | 422 | Submit: the company asks for a receipt and the claim has none. Attach it, or turn off Receipt required. The other expense-claim refusals are listed under When a claim is refused. |
expense_claim_period_locked | 422 | Approve: the claim is dated in a locked period. Send book_in_open_period: true. |
period_locked | 422 | Another expense-claim write (a payment, or an update or decline of an approved claim) would post in a locked period. |
bill_paid_already | 409 | Pay bills holds the bill as paid already. Take the mark back with bill.paidAlready.undo first. |
bill_in_bank_file | 409 | The bill is in a bank file. Put it back to To pay in Cybooks first. |
bill_void_not_open | 409 | Only an open, unsettled bill is voided. |
bill_void_active_payment | 422 | A payment settles the bill. Reverse it first. |
bill_void_vendor_credit | 422 | A vendor credit is applied to the bill. Remove it first. |
bill_totals_mismatch | 422 | The bill's totals don't add up to its lines (net or gross, beyond the lines' rounding), so it can't post. The totals follow the lines on the API: update the lines so they add up to the document, then post. error.fields names the total that differs. |
bill_void_no_journal | 422 | The bill has no posting entry to reverse. |
bill_void_unbalanced_journal | 422 | A void, its reversal or a moved reversal would write an entry that is not the exact mirror of the one it reverses and does not balance. The exact mirror of an unbalanced entry is always written: it nets that entry to zero. Nothing was changed. |
bill_void_reverse_not_voided | 409 | Only a voided bill's void is reversed. |
bill_void_reverse_no_journal | 422 | The voided bill has no void entry left to reverse. |
bill_void_reversal_date_before_bill | 422 | reversal_date is before the bill's date or one of its posting entries. |
bill_void_reversal_date_future | 422 | reversal_date is after today (Nicosia). |
bill_void_reversal_date_locked_period | 422 | reversal_date is in a locked period. Pick a day after the lock. |
bill_void_reversal_date_filed_vat_period | 422 | reversal_date is in a VAT or OSS period already filed in Cybooks. |
bill_void_reversal_date_financial_year | 422 | The bill's entry is in a locked period, so its reversal stays in that financial year. |
bill_void_redate_not_voided | 409 | Only a voided bill has a void reversal to move. |
bill_void_redate_no_journal | 422 | The voided bill has no void entry left to move. |
bill_void_redate_same_date | 422 | The void's reversal is already on that day. |
bill_void_redate_reversal_locked_period | 409 | The void's reversal is in a locked period, so it stays where it is. |
bill_void_redate_reversal_filed_vat_period | 409 | The void's reversal is in a filed VAT period, so it stays where it is. |
bill_void_redate_stock | 409 | The bill moved stock: its stock movements cannot move with the reversal, so a stock bill's reversal stays where it is. |
bill_void_redate_token_invalid | 422 | The confirmation token was sent with another Idempotency-Key, by another person, for another company or operation, or it expired. Preview again. |
bill_paid_already_undo_not_marked | 409 | No paid-already mark holds the bill: nothing to take back. |
bill_paid_already_undo_line_found | 409 | The mark's bank line arrived and waits for a person in Banking. Book it, or settle the bill, in Cybooks. |
bill_paid_already_undo_settling | 409 | The mark's bank line is being booked right now. Read the bill again in a few minutes. |
bill_paid_already_undo_settled | 409 | The bill was settled, by its bank line or another way. Undo that payment instead. |
bill_paid_already_undo_token_invalid | 422 | The confirmation token was sent with another Idempotency-Key, by another person, for another company or operation, or it expired. Preview again. A token previewed for another bill or mark answers 412. |
Each code is in error.code and at the start of error.message.
Finding a bill for a quarter close
filter[number] matches the supplier document number exactly. filter[date_from] and filter[date_to] include both ends of the document-date range (YYYY-MM-DD). filter[amount], filter[amount_min] and filter[amount_max] compare the gross amount in the bill currency, rounded to the two decimals the API shows, with inclusive bounds. All filters intersect; malformed dates, inverted ranges and unknown keys are refused.
For compact pages, use the existing fields[bills]=id,document_number,vendor_id,date_of_document,amount_gross_total,status. This excludes line items and other unselected nested data. In MCP the same option is query.fields.bills, and filters belong in query.filter.
Updated 6 days ago
