Preview a correction of an approved bill

Shows what correcting an approved bill would change, without writing anything: the supplier (vendor_id), the supplier's number (document_number), the description, and per line (named by its id) the account (account_id or account_code), the tax rule (tax_rule_id or tax_code), the description and the IP Box fields (ip_box_category, ip_box_percentage, ip_box_asset_id, set as the bill page sets them: a category without a percentage claims 100%, a null category clears the percentage and the asset). A line sent as {id, remove: true} is removed, as deleting its row on the bill page does: the totals drop by its net, VAT and gross, the journal is re-posted from the lines left, changes.removed_line_items lists it, and on a bill with payments or vendor credits the open amount drops by as much (a bill its payments now cover is paid). Every field a line does not send stays exactly as stored, IP Box fields included, and so does every bill field the request does not change (the exchange rate among them). A foreign-currency bill with no exchange rate Cybooks can post with (none, or a bare 1 with no source) takes the rate of its date only when the request sends missing_exchange_rate: "document_date": the ECB rate saving the bill in the app gives it, shown in changes.exchange_rate (from and to), with the journal and VAT boxes at that rate. date_of_document (YYYY-MM-DD) moves the bill's date as the bill page does: the journal is re-posted on it, payments and vendor credits keep their own dates and journals, a foreign-currency bill takes the ECB rate of the new date (changes.exchange_rate), and a bill with a preset payment term takes the due date the term gives the new date unless due_date is sent (due_date alone moves the due date; one the term would not give makes the term custom, as the bill page does). Both the old and the new date must be in an open, unfiled period; a bill in a bank file or marked paid already can be re-dated (Pay bills holds its supplier and open amount). The preview then shows changes.date_of_document, changes.due_date and changes.payment_term, the journal's dates_before and dates, and vat_periods: the boxes that move per VAT period, the old period and the new (an estimate from each line's VAT; the journal is what posts). Returns the changes (per line, fields lists every line field that would change, from and to, so nothing changes unseen), the totals before and after, the bill journal before and after re-posting per account (base currency), the VAT return boxes the change moves, warnings and the confirmation token bill.correct needs. Refusals name their code in error.code and at the start of the message: bill_correct_draft, bill_correct_voided, bill_correct_not_posted, bill_correct_period_locked, bill_correct_vat_filed, 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), bill_correct_below_paid (a removal that takes the total below what the bill has paid or had credited), bill_correct_keep_a_line (a removal of every line: void the bill instead), bill_correct_total_not_positive (a removal that takes the total to zero or below), bill_correct_awaiting_approval (a removal on a bill with payments that waits for approval), bill_totals_mismatch (the totals left would not agree with the lines left), bill_in_bank_file (a supplier change or a removal while the bill is in a bank file: put it back to To pay in Cybooks), bill_paid_already (a supplier change or a removal while it is marked paid already: take the mark back with bill.paidAlready.undoPreview then bill.paidAlready.undo), bill_correct_stock_line, bill_correct_fixed_asset_line (both also for a removed line stock or a fixed asset was built from), bill_correct_import_vat, bill_correct_no_change, bill_correct_line_unknown, bill_correct_account_unavailable, bill_correct_tax_rule_unavailable, bill_correct_vendor_unavailable, bill_correct_ip_box_invalid, bill_correct_ip_box_no_category (a percentage or asset on a line without an IP Box category), bill_correct_ip_box_capitalized (an IP Box change on, or the removal of, a line in an IP Box capitalization), bill_correct_exchange_rate_unusable (a foreign-currency bill with no rate Cybooks can post with, and no missing_exchange_rate), 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 on a bill with payments or vendor credits: undo them first; on a bill that made a fixed asset (delete it first) or has an IP Box capitalization it is bill_correct_fixed_asset_line or bill_correct_ip_box_capitalized), bill_correct_exchange_rate_unavailable (no rate for the bill's date or its new date), bill_correct_due_before_date (a due_date before the bill's date); a new date is also refused with bill_correct_period_locked or bill_correct_vat_filed when the old or the new date is closed or filed, with bill_correct_exchange_rate_paid on a foreign-currency bill with payments or vendor credits, and with bill_correct_fixed_asset_line, bill_correct_ip_box_capitalized, bill_correct_import_vat or bill_correct_stock_line on a bill a fixed asset, an IP Box capitalization, import VAT or stock was built from, with bill_correct_landed_cost on a bill with a customs record or a landed cost applied from it, and with bill_correct_accrual_exchange_rate on a foreign-currency bill whose service period ends before the new date; 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) is refused with bill_in_bank_file or bill_paid_already while Pay bills holds the bill. The required Idempotency-Key binds the token; send the same key and body to bill.correct. Requires the bills:action OAuth scope.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required
Body Params

Proposed values used to preview a correction of an approved bill without persisting changes.

What a correction of an approved bill may change: the supplier, the
supplier's document number, the description, and per line the account,
the tax rule, the description and the IP Box category, percentage and
asset. Lines are named by the id the bill returns; a line left out, and
every field a line does not send, keeps what it has. A line sent with
remove: true (and nothing else) is removed. A foreign-currency
bill without an exchange rate Cybooks can post with takes the rate of its
date only when asked (missing_exchange_rate). The bill's date
(date_of_document) and due date (due_date) move as on the bill page.

uuid

The supplier the bill belongs to (from the vendors list).

string
length ≤ 255

The supplier's own invoice number.

string | null
string
enum

Only for a foreign-currency bill with 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): document_date gives it the rate of its date, as saving it in the app does (ECB), and re-posts its journal at that rate. Left out, such a bill is refused with bill_correct_exchange_rate_unusable. Refused on a bill that has a rate (bill_correct_exchange_rate_present), on one with payments or vendor credits (bill_correct_exchange_rate_paid), on one with a line that made a fixed asset or is in an IP Box capitalization (bill_correct_fixed_asset_line, bill_correct_ip_box_capitalized) and when there is no rate for its date (bill_correct_exchange_rate_unavailable).

Allowed:
date

The bill's new date (YYYY-MM-DD). The bill's journal is re-posted on it, as saving the bill in the app does; payments and vendor credits keep their own dates. A foreign-currency bill takes the ECB rate of the new date, as the app gives it (refused with bill_correct_exchange_rate_paid on one with payments or vendor credits). Both the old and the new date must be in an open period no filed VAT return covers (bill_correct_period_locked, bill_correct_vat_filed). Refused on a bill a fixed asset was made from (bill_correct_fixed_asset_line), with a line in an IP Box capitalization (bill_correct_ip_box_capitalized), with an import VAT line (bill_correct_import_vat), that receives stock (bill_correct_stock_line) or with a customs record or a landed cost applied from it (bill_correct_landed_cost), and on a foreign-currency bill whose service period ends before the new date (bill_correct_accrual_exchange_rate). Refused while Pay bills holds the bill and the new date changes what an approval policy may ask again on, the due date its payment term gives or a foreign-currency bill's amount at the new rate (bill_in_bank_file, bill_paid_already). Not with missing_exchange_rate.

date | null

The bill's new due date (YYYY-MM-DD), on or after its date; null clears it. Left out with a new date_of_document, 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, and any other bill keeps its due date. A due date the term would not give makes the term custom, as the bill page does. Refused while Pay bills holds the bill and an approval policy may send it back for approval (bill_in_bank_file, bill_paid_already).

line_items
array of objects
length between 1 and 500

The lines to correct; a line not listed keeps its account, tax rule and description.

line_items
Headers
string
required
length ≤ 191

Required operation-specific request key. This requirement does not imply durable public API response replay.

Responses

Language
Credentials
OAuth2
Missing 1 required scope
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
*/*