Update Document
Correct a document the company issued, as long as it has gone nowhere yet.
Once a document has left — by mail or over Peppol — it is issued, and correcting it is no
longer allowed: issue a credit note instead. The two channels are independent, so both are
checked. Once it has been handed to the accounting (accounting_status beyond waiting and
export_error), it lives in the accountant’s system too, and changing it here would leave
the two disagreeing. Either gives 409 document_not_editable, saying which one blocks. A
document the company received cannot be modified either. What has been paid, on the other
hand, never blocks: that belongs to the bank reconciliation.
Only the fields present in the body are applied. type and journal_id are read-only —
the document’s number was drawn from that journal’s sequence for that type. due_date and
relation_type are accepted but ignored, like at creation, so a document that was read can
be sent back unchanged.
paid_amount records a payment Fidly cannot see for itself — cash, or a transfer on an
account it does not follow. It may not exceed the document’s total, and payment_status
follows it; the payments Fidly does see are written by its bank reconciliation instead.
lines and allowance_charges replace the whole list rather than merging into it: a
line has no identity of its own, so there is nothing a partial update could address, and
adding, removing or reordering would not be expressible. Send them and every amount is
recomputed — the VAT of each rate, the document’s discounts spread over those rates, the
totals and the euro conversion. Omit them and the stored lines are not even re-read.
issue_date must stay inside the window its number was drawn in: free when the journal’s
counter never restarts, the same month or the same year otherwise. Changing it, or the
payment_terms, re-derives the due date.
The PDF and the Peppol XML are regenerated asynchronously and replace the previous ones; until they do, downloading the file still returns the version before this change. A request that breaks a rule is refused as a whole: the document is left untouched.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Body
The editable part of a document it issued. Every field is optional: only the ones actually present in the request body are applied, so omitting a field leaves it untouched.
lines and allowance_charges are replacements, not merges: sending them replaces the
whole list. A document line has no identity of its own — its sequence is its position, and
is reassigned on every write — so there is nothing to address a partial line update to, and
adding, removing or reordering would not be expressible.
Read-only after creation.
Read-only after creation.
Amount already paid, tax included, for a payment that reached the company through a channel Fidly does not read — cash, or a transfer on an account it does not follow. Drives payment_status, and may not exceed the document's total. Payments Fidly does see are written by its bank reconciliation, not here.
0 <= x <= 999999999Opaque identifier of the third party the document is issued to. It says by itself whether it is a company or a contact.
Ignored: read from relation_id, like at creation.
Ignored: files are attached with POST /documents/{id}/attachments, never through this body. Accepted so a document that was read can be sent back unchanged.
Date the document is issued. Never in the future, and it must stay in the window the document's number was drawn in — free in the past when the journal's counter never restarts, the same month or the same year otherwise.
Ignored: always derived from payment_terms, as at creation.
Payment terms, as <days>-<basis> (df, fm, mf). Changing them re-derives the due date.
^\d{1,4}-(df|fm|mf)$One of the third party's saved delivery addresses, or null to detach the one currently set.
Date the VAT becomes chargeable.
Date of the actual delivery — today or earlier, never a future date.
First day of the billed period.
Last day of the billed period.
Order number.
255Reference of the despatch advice.
50Reference given by the buyer.
50Legal mention printed at the bottom of the document. null clears it.
10000ISO 4217 currency code of every amount.
20Replaces all the lines of the document. At least one is required — a document without lines is not representable — and 500 at most.
1 - 500 elementsReplaces all the discounts/surcharges of the document. An empty list removes them.
50Response
Successful Response
A document of the company: an invoice/credit note it issued or a document it
received (purchase invoice, credit note, other). The source table is hidden — the
client sees a single unified document identified by an opaque id.
Monetary amounts are decimal numbers in the document's currency. They may be null
when the document could not be parsed automatically, or for other_document types
that have no financial breakdown.
Both sources are normalised to this shape by the repository adapters; the validators below map the internal codes to their public values.
Opaque unique identifier of the document.
Document type. One of: sale_invoice, sale_credit_note, purchase_invoice, purchase_credit_note, other_document, unknown.
Channel the document came in through. One of: fidly (generated in Fidly), manual, peppol, mail, odoo, billit, api (or unknown).
The document's own number (e.g. invoice number).
Purchase/sales order number referenced by the document.
Reference of the despatch advice (delivery note) related to the document.
Reference given by the buyer, to be quoted back on the document (e.g. a cost centre).
Date the document was issued (ISO YYYY-MM-DD).
Payment due date (ISO YYYY-MM-DD).
Date the VAT becomes chargeable, when it differs from the issue date (ISO YYYY-MM-DD).
Date the goods/services were actually delivered (ISO YYYY-MM-DD).
First day of the period the document bills (ISO YYYY-MM-DD).
Last day of the period the document bills (ISO YYYY-MM-DD).
Communication to quote when paying the document. null when the document carries none.
true when payment_remittance is a structured communication (a bank-checked reference such as a Belgian OGM/VCS) rather than free text. Always true for documents issued by Fidly.
Timestamp the document was created in Fidly (ISO 8601). May be null on rare legacy rows where it was never set.
ISO 4217 currency code of all amounts (e.g. EUR).
Total amount excluding tax.
Total tax (VAT) amount.
Total amount payable, tax included.
Amount already paid.
Amount still to be paid (total_amount minus paid_amount).
Payment state. One of: unpaid, partial, paid (or unknown).
Accounting workflow state. One of: waiting, accepted, transfered, exported, export_error, imported, validated, hidden, exporting, posting, posting_error, deleted (or unknown).
true if a PDF is stored for this document (retrievable via the file endpoint).
true if a structured XML version (e.g. Peppol/UBL) is stored for this document.
Nature of relation_id: company (a registered business relation) or contact (an individual contact). null when there is no linked third party.
Opaque identifier of the third party the document is linked to (resolvable via GET /relations/{id}). Its nature is given by relation_type. null when the document has no linked third party.
Opaque identifier of the journal the document is booked in (resolvable via GET /journals/{id}). null when the document has no linked journal.
Opaque identifier of the saved delivery address the document is delivered to (resolvable via GET /delivery-locations/{id}). null when none is set.
Payment terms the due_date follows from, as <days>-<basis> (e.g. 30-df). Always null on a received document: only documents Fidly issues carry them.
Legal mention printed at the bottom of the document (e.g. a VAT exemption wording). Always null on received documents.
Peppol send state of an issued document. One of: not_sent, sending, sent (delivered to the network), accepted (acknowledged by the recipient), rejected (refused by the recipient), failed (or unknown). rejected and failed can be sent again. Always null on a received document.
E-mail send state of an issued document. One of: not_sent, sent, failed (or unknown). Always null on a received document.
Files attached to the document, in the order they were added. Attach one with POST /documents/{id}/attachments; the API offers no way to remove one. A received document never carries any.
Discounts/surcharges applied to the document as a whole, after the lines and their own. tax_exclusive_amount is already net of them.
Detailed lines of the document (invoiced items/services). Empty when none are stored.