Correcting approved bills
Correcting approved bills
A draft bill is changed with PATCH /v1/bills/{id} (cybooks_update_bill
over MCP). An approved bill, one that is open, partly paid or paid, is
corrected in two steps, the way saving it on the bill page does:
POST /v1/bills/{id}/correct/preview(cybooks_bill_correct_preview)
shows what the correction would change and returns aconfirmation_token.
It writes nothing.POST /v1/bills/{id}/correct(cybooks_bill_correct) applies it. Send the
same body andIdempotency-Keyas the preview, the preview's
confirmation_token, and the bill's ETag inCybooks-If-Match(or the standardIf-Match).
The bill is updated and its journal re-posted on the same dates (or on its
new date, when the correction moves it). Payments and vendor credits stay on
the bill.
A correction can also remove a line, for example the same item entered
twice (see Removing a line), or move the bill's date (see
Changing the date).
What a correction can change
| Field | Where |
|---|---|
vendor_id | the supplier |
document_number | the supplier's own invoice number |
description | the bill's description |
line_items[].account_id or account_code | a line's account |
line_items[].tax_rule_id or tax_code | a line's tax rule |
line_items[].description | a line's description |
line_items[].ip_box_category | a line's IP Box category: ip_direct_cost, ip_qe_expensed, ip_qe_capitalized or ip_cost_of_acquisition; null takes the line out of the IP Box |
line_items[].ip_box_percentage | the share of the line claimed under the IP Box, 0 to 100, two decimals at most |
line_items[].ip_box_asset_id | the IP Box asset the line belongs to; null clears it |
line_items[].remove | true removes the line from the bill; send it with the line's id only |
missing_exchange_rate | document_date only: a foreign-currency bill without an exchange rate Cybooks can post with takes the rate of its date (below) |
date_of_document | the bill's date, YYYY-MM-DD (Changing the date) |
due_date | the bill's due date, YYYY-MM-DD, on or after its date; null clears it |
Lines are named by the id the bill returns. A line you leave out, and every
field a line does not send, stays exactly as it is: its quantity, unit price,
amount, discount, tags, product, IP Box fields and everything else. Correcting
a line's account does not touch its IP Box category or percentage. The same
holds for the bill itself: its exchange rate, dates, payment terms, branch,
creator and every other field you do not send stay as they are; only the
totals follow a tax rule change, and the exchange rate changes only when you
send missing_exchange_rate, or a new date on a foreign-currency bill
(below). A bill with payments keeps its paid and open
amounts exactly as they are, also when it was paid from a bank account in
another currency.
The IP Box fields follow the bill page's rules:
- A category without a percentage keeps the line's percentage, or claims 100%
when the line had no category before. - A
nullcategory clears the percentage and the asset too: a line outside
the IP Box carries neither. - A percentage or an asset on a line that has, or is left with, no category is
refused withbill_correct_ip_box_no_category. - A line in an IP Box capitalization keeps its IP Box fields
(bill_correct_ip_box_capitalized): reverse the capitalization in Cybooks
first.
Removing a line
Send the line's id with remove: true, as deleting its row on the bill page
does:
{ "line_items": [{ "id": "0b8f2f0e-…", "remove": true }] }Remove one line or several in the same correction, alone or with the other
changes. A removed line takes nothing else: a line that sends remove: true
with any other field is refused by validation.
- The bill's net, VAT and gross drop by the removed line's own net, VAT and
gross; the other lines keep exactly what they have. A header that carries
a few cents of rounding beside its lines, more than the fewer lines left
allow, follows the lines left instead, as saving the bill page does; the
preview'stotalsshow it. - The journal is re-posted from the lines left, on the same dates and at the
bill's own exchange rate, so the expense, the VAT and the payable each drop
by the line's share. - The preview lists each removed line in
changes.removed_line_items(its
id, description, account, tax rule, quantity,amount,net,vatand
gross), with the journal before and after and the VAT return boxes the
removal moves (vat_boxes). - A bill with payments or vendor credits keeps them. Its open amount drops by
what the total drops, and once the payments cover the new total the bill is
paid: a bill of 238.00 with 119.00 paid that loses a doubled 119.00 line is
paid, with nothing open.payments.unpaid_amountandpayments.statusin
the preview show both before and after. - The bill's audit trail keeps every removed line as it was.
Refused:
| Code | Why |
|---|---|
bill_correct_below_paid | the new total would be less than the bill has paid or had credited: remove fewer lines, or undo the payment first |
bill_correct_keep_a_line | the correction would remove every line: void the bill instead |
bill_correct_total_not_positive | the lines left would add up to zero or less: void the bill instead |
bill_correct_awaiting_approval | the bill has payments and waits for approval: approve it in Cybooks first |
bill_correct_line_unknown | the id is not a line of this bill |
bill_correct_fixed_asset_line | the line made a fixed asset: delete the asset in Cybooks first |
bill_correct_ip_box_capitalized | the line is in an IP Box capitalization: reverse it in Cybooks first |
bill_correct_stock_line | the line receives stock, or adds to the cost of the bill's stock: remove it on the bill page |
bill_in_bank_file, bill_paid_already | Pay bills holds the bill for its old open amount |
bill_correct_period_locked, bill_correct_vat_filed | as for every correction: the bill posts in a closed period or a filed VAT period |
On a bill with payments or vendor credits only a removal that lowers the
total may change it: removing a negative line (which raises it), or a tax
rule change that moves it, is still bill_correct_total_paid.
Changing the date
Send the new date, as changing it on the bill page does:
{ "date_of_document": "2026-08-11" }- The bill's journal is re-posted on the new date, with the same amounts.
Payments and vendor credits keep their own dates and journals; a payment
dated before the new date stays where it is, as in the app (the preview
warns about it). due_datemoves the due date. Left out, a bill with a payment term
(net15,net30,net45,end_of_month,due_next_month,
due_on_receipt) takes the due date the term gives the new date, as the
bill page does; any other bill keeps its due date (the preview warns when
it is left before the new date). Adue_datethe payment term would not
give the date makes the termcustom, as editing the due date on the bill
page does (changes.payment_term), so the page does not re-derive it. A
due_datebefore the bill's date is refused with
bill_correct_due_before_date. A due date sent alone re-saves the bill as
the bill page does: its journal is re-posted unchanged on its date, so the
bill's date must be open and unfiled for that too.- An approval policy asks again when the due date changes (sent, or derived
from the payment term for a new date) and when a foreign-currency bill's
amount changes with the new date's exchange rate. While a policy may send
the bill back for approval, a bill in a Pay bills bank file or marked paid
already is refused (bill_in_bank_file,bill_paid_already; the message
names what would change). Otherwise the correction goes through and the
preview says the Pay bills payment stays as it is. - A foreign-currency bill takes the ECB rate of the new date, as saving it in
the app does (a typed rate is replaced too; the preview warns), shown in
changes.exchange_rate, and its journal is re-posted at it. A
foreign-currency bill with payments or vendor credits is refused
(bill_correct_exchange_rate_paid): the payments keep the rate they were
posted at. No rate for the new date:bill_correct_exchange_rate_unavailable.
A base-currency bill keeps its rate.missing_exchange_rateis not sent
with a new date: the new date gives the rate. A foreign-currency bill whose
service period ends before the new date is refused
(bill_correct_accrual_exchange_rate): it would post an accrual at the rate
of that day, which the posting looks up itself. - Both the old and the new date must be in an open period that no filed VAT
return covers (bill_correct_period_locked,bill_correct_vat_filed; the
message names the date). So must the service period's end when the new
date is after it (the bill then posts an accrual there). - A bill in a Pay bills bank file, or marked paid already, can be re-dated:
Pay bills holds its supplier and open amount, which a date change keeps.
The preview warns about payments and vendor credits dated before the new
date, and a Pay bills date before it.
The preview shows changes.date_of_document, changes.due_date and
changes.payment_term (from and to), the days the journal posts on now
and after (journal.dates_before, journal.dates) and, per VAT period, the
boxes that move (vat_periods): a date that moves the bill into another VAT
period lists the old period losing what the new one gains, while vat_boxes
(the net over every period) may then be empty. vat_periods places the bill
as it posts: its VAT in the period of its date, its net there too or, on an
accrual bill (a service period ending before its date), in the period of the
service period's end. It is an estimate from each line's own VAT: where the
allowable input VAT cap claims less, box 4 shows more than the return will.
The journal (journal.after, journal.dates) is what posts.
{
"changes": { "date_of_document": { "from": "2026-09-11", "to": "2026-08-11" }, "due_date": null },
"journal": { "dates_before": ["2026-09-11"], "dates": ["2026-08-11"], "changes": [] },
"vat_periods": [
{ "period": { "start": "2026-06-01", "end": "2026-08-31" }, "boxes": [{ "box": "box-4", "from": "0.00", "to": "19.00", "change": "19.00" }] },
{ "period": { "start": "2026-09-01", "end": "2026-11-30" }, "boxes": [{ "box": "box-4", "from": "19.00", "to": "0.00", "change": "-19.00" }] }
]
}Refused, because the re-dated save cannot move what was built from the bill
on its old date:
| Code | Why |
|---|---|
bill_correct_fixed_asset_line | a fixed asset was made from the bill (draft, registered or disposed): its acquisition is the bill's date. Delete the asset in Cybooks first |
bill_correct_ip_box_capitalized | a line is in an IP Box capitalization, whose tax year follows the bill's date |
bill_correct_import_vat | an import VAT line: its claim follows the customs declaration |
bill_correct_stock_line | the bill receives stock or adds to its cost: the receipt would move under the stock sold since |
bill_correct_landed_cost | the bill has a customs record, or its duty or fees went into stock or an asset's cost (landed cost): re-posting would apply them again on the new date and re-cost that stock |
bill_correct_accrual_exchange_rate | a foreign-currency bill whose service period ends before the new date |
The token binds the old and the new date, the due date and the payment term:
a commit with another date, or without it, is refused with
412 Precondition Failed.
A foreign-currency bill without an exchange rate
Some foreign-currency bills carry no exchange rate Cybooks can post with: the
bill's exchange_rate is null, or exactly 1 with neither is_custom
true nor source ecb (bills converted from the inbox before August 2026
were saved that way and posted one to one). Saving such a bill on the bill page
gives it the rate of its date. A correction does the same only when you ask
for it:
{ "missing_exchange_rate": "document_date" }Send it alone, or with the other changes. The rate is the ECB rate of the
bill's date, from the same source the bill page's save uses, stored with
source: "ecb". The bill's own amounts stay in its currency; its journal is
re-posted at the new rate, so the payable, the expense and the VAT move in
the base currency. The preview shows all of it:
changes.exchange_rate: the rate before (nullwhen there was none) and
after, as the bill returns it (rate,date,is_custom,source);journal: the journal now and at the new rate, per account;vat_boxes: every box the bill's lines move at the new rate.
{
"exchange_rate": {
"from": null,
"to": { "rate": "1.17250000", "date": "2026-06-03", "is_custom": false, "source": "ecb" }
}
}Until it has its rate, such a bill takes no payment: matching it to a bank
line is refused with candidate_exchange_rate_missing, which points here.
Without missing_exchange_rate, such a bill is refused with
bill_correct_exchange_rate_unusable, whatever else the correction changes:
a correction does not set a rate you did not ask for. The token binds the
choice and the rate: a commit that leaves missing_exchange_rate out after a
preview that sent it, or that would post at another rate than the preview
showed, is refused with 412 Precondition Failed.
A bill with payments or vendor credits is refused
(bill_correct_exchange_rate_paid): the payments keep the rate they were
posted at, and re-measuring the payable under them needs a realised exchange
difference. Undo the payment first (unmatch the bank line, reverse a payment
recorded over the API, or reverse a vendor credit application), give the bill
its rate, then record the payment again. A bill with a line that made a
fixed asset (bill_correct_fixed_asset_line: delete the asset first; a bill
whose asset was disposed of keeps its rate) or is in an IP Box capitalization
(bill_correct_ip_box_capitalized) keeps its rate too: their cost was built
at the rate the bill was posted at.
Reading the preview
changes.line_items has one entry per line that would change. fields lists
every line field that changes, with its value before (from) and after
(to), as text (null when empty):
{
"id": "0b8f2f0e-…",
"account": { "from": { "id": "264", "code": "6300", "name": "Office" }, "to": { "id": "172", "code": "6100", "name": "Rent" } },
"ip_box": null,
"fields": [
{ "field": "chart_of_account_id", "from": "264", "to": "172" }
]
}Setting an IP Box category on a line shows both the ip_box summary and each
field:
{
"ip_box": {
"from": { "category": null, "percentage": null, "asset_id": null },
"to": { "category": "ip_qe_expensed", "percentage": "100", "asset_id": null }
},
"fields": [
{ "field": "ip_box_category", "from": null, "to": "ip_qe_expensed" },
{ "field": "ip_box_percentage", "from": null, "to": "100" }
]
}A field that is not in fields does not change. The commit checks this: after
saving, it reads the bill and every line again, and if any field differs from
what the preview showed it is refused with bill_correct_unplanned_change and
nothing is saved.
Every correction checks that the totals it leaves agree with the lines it
leaves, as posting the bill does: one that would not is refused at the
preview with bill_totals_mismatch, and nothing is changed.
The preview also returns the totals before and after, the bill's journal before
and after re-posting per account in the base currency, the VAT return boxes the
correction moves, and warnings (an approval policy that may ask again, a bill
that looks like a duplicate after the change).
Refusals
Each refusal names its code in error.code and at the start of the message.
| Code | Why |
|---|---|
bill_correct_draft | a draft: use PATCH /v1/bills/{id} |
bill_correct_voided, bill_correct_not_posted | the bill is voided, or not approved |
bill_correct_period_locked, bill_correct_vat_filed | the bill posts, or a new date would post it, in a closed period or a filed VAT period |
bill_correct_vendor_paid | a supplier change on a bill with payments or vendor credits |
bill_correct_total_paid | a tax rule change that changes the total of a bill with payments or vendor credits, or a removal that raises it |
bill_correct_below_paid, bill_correct_keep_a_line, bill_correct_total_not_positive | a removal that takes the total below what is paid, removes every line, or leaves a total of zero or less (Removing a line) |
bill_totals_mismatch | the totals the correction leaves would not agree with its lines |
bill_in_bank_file, bill_paid_already | a supplier change or a removed line while Pay bills holds the bill, or a date or due date change that changes what an approval policy may ask again on (the due date, a foreign-currency bill's amount at the new rate) while it holds the bill. A bill marked paid already is freed with "Not paid yet" (bill.paidAlready.undo, see Bills); a bill in a bank file is put back to To pay in Cybooks |
bill_correct_stock_line, bill_correct_fixed_asset_line, bill_correct_import_vat | a line whose account or tax rule the bill page locks, or a removed line stock, a fixed asset or an IP Box capitalization was built from |
bill_correct_ip_box_invalid, bill_correct_ip_box_no_category, bill_correct_ip_box_capitalized | an IP Box value the bill page would not accept on that line |
bill_correct_exchange_rate_unusable | a foreign-currency bill with no exchange rate Cybooks can post with: send missing_exchange_rate: "document_date" |
bill_correct_exchange_rate_present | missing_exchange_rate on a bill that has a rate, or is in the base currency |
bill_correct_exchange_rate_paid | missing_exchange_rate, or a new date, on a foreign-currency bill with payments or vendor credits: undo them first |
bill_correct_exchange_rate_unavailable | no rate for the bill's date, or its new date (the ECB publishes none for the currency or the day, or did not answer): try again later |
bill_correct_due_before_date | a due_date before the bill's date |
bill_correct_no_change | every value sent is the bill's own already |
bill_correct_line_unknown, bill_correct_account_unavailable, bill_correct_tax_rule_unavailable, bill_correct_vendor_unavailable | an id or code that does not name a line, account, tax rule or supplier of this company |
bill_correct_token_invalid | the token is expired, or for another request |
bill_correct_unplanned_change | the save would have changed something the preview did not show; nothing was saved |
A bill that changed between the preview and the commit, or a commit whose
missing_exchange_rate, date, due date or rate differs from its preview's, is
refused with 412 Precondition Failed: preview again.
Updated 10 days ago
