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:

  1. POST /v1/bills/{id}/correct/preview (cybooks_bill_correct_preview)
    shows what the correction would change and returns a confirmation_token.
    It writes nothing.
  2. POST /v1/bills/{id}/correct (cybooks_bill_correct) applies it. Send the
    same body and Idempotency-Key as the preview, the preview's
    confirmation_token, and the bill's ETag in Cybooks-If-Match (or the standard If-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

FieldWhere
vendor_idthe supplier
document_numberthe supplier's own invoice number
descriptionthe bill's description
line_items[].account_id or account_codea line's account
line_items[].tax_rule_id or tax_codea line's tax rule
line_items[].descriptiona line's description
line_items[].ip_box_categorya 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_percentagethe share of the line claimed under the IP Box, 0 to 100, two decimals at most
line_items[].ip_box_asset_idthe IP Box asset the line belongs to; null clears it
line_items[].removetrue removes the line from the bill; send it with the line's id only
missing_exchange_ratedocument_date only: a foreign-currency bill without an exchange rate Cybooks can post with takes the rate of its date (below)
date_of_documentthe bill's date, YYYY-MM-DD (Changing the date)
due_datethe 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 null category 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 with bill_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's totals show 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, vat and
    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_amount and payments.status in
    the preview show both before and after.
  • The bill's audit trail keeps every removed line as it was.

Refused:

CodeWhy
bill_correct_below_paidthe 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_linethe correction would remove every line: void the bill instead
bill_correct_total_not_positivethe lines left would add up to zero or less: void the bill instead
bill_correct_awaiting_approvalthe bill has payments and waits for approval: approve it in Cybooks first
bill_correct_line_unknownthe id is not a line of this bill
bill_correct_fixed_asset_linethe line made a fixed asset: delete the asset in Cybooks first
bill_correct_ip_box_capitalizedthe line is in an IP Box capitalization: reverse it in Cybooks first
bill_correct_stock_linethe 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_alreadyPay bills holds the bill for its old open amount
bill_correct_period_locked, bill_correct_vat_filedas 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_date moves 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). A due_date the payment term would not
    give the date makes the term custom, as editing the due date on the bill
    page does (changes.payment_term), so the page does not re-derive it. A
    due_date before 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_rate is 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:

CodeWhy
bill_correct_fixed_asset_linea 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_capitalizeda line is in an IP Box capitalization, whose tax year follows the bill's date
bill_correct_import_vatan import VAT line: its claim follows the customs declaration
bill_correct_stock_linethe bill receives stock or adds to its cost: the receipt would move under the stock sold since
bill_correct_landed_costthe 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_ratea 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 (null when 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.

CodeWhy
bill_correct_drafta draft: use PATCH /v1/bills/{id}
bill_correct_voided, bill_correct_not_postedthe bill is voided, or not approved
bill_correct_period_locked, bill_correct_vat_filedthe bill posts, or a new date would post it, in a closed period or a filed VAT period
bill_correct_vendor_paida supplier change on a bill with payments or vendor credits
bill_correct_total_paida 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_positivea 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_mismatchthe totals the correction leaves would not agree with its lines
bill_in_bank_file, bill_paid_alreadya 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_vata 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_capitalizedan IP Box value the bill page would not accept on that line
bill_correct_exchange_rate_unusablea foreign-currency bill with no exchange rate Cybooks can post with: send missing_exchange_rate: "document_date"
bill_correct_exchange_rate_presentmissing_exchange_rate on a bill that has a rate, or is in the base currency
bill_correct_exchange_rate_paidmissing_exchange_rate, or a new date, on a foreign-currency bill with payments or vendor credits: undo them first
bill_correct_exchange_rate_unavailableno 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_datea due_date before the bill's date
bill_correct_no_changeevery value sent is the bill's own already
bill_correct_line_unknown, bill_correct_account_unavailable, bill_correct_tax_rule_unavailable, bill_correct_vendor_unavailablean id or code that does not name a line, account, tax rule or supplier of this company
bill_correct_token_invalidthe token is expired, or for another request
bill_correct_unplanned_changethe 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.


Did this page help you?