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.

PATCH /documents/{document_uuid}

Update Document

cURL

curl --request PATCH \
  --url https://api.fidly.be/documents/{document_uuid} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "journal_id": "<string>",
  "paid_amount": 499999999.5,
  "relation_id": "<string>",
  "relation_type": "<string>",
  "attachments": [
    "<unknown>"
  ],
  "issue_date": "2023-12-25",
  "due_date": "2023-12-25",
  "payment_terms": "<string>",
  "delivery_location_id": "<string>",
  "tax_point_date": "2023-12-25",
  "delivery_date": "2023-12-25",
  "period_start": "2023-12-25",
  "period_end": "2023-12-25",
  "order_number": "<string>",
  "despatch_reference": "<string>",
  "buyer_reference": "<string>",
  "legal_notice": "<string>",
  "currency": "<string>",
  "lines": [
    {
      "item_name": "<string>",
      "quantity": 0,
      "unit_price": 499999999.5,
      "vat_code": "<string>",
      "vat_rate": 50,
      "sequence": 123,
      "subtotal": 123,
      "total": 123,
      "tax_amount": 123,
      "item_description": "<string>",
      "section_name": "<string>",
      "unit_code": "C62",
      "item_properties": {},
      "item_identification": "<string>",
      "product_code": "<string>",
      "allowance_charges": [
        {
          "type": "<string>",
          "amount": 499999999.5,
          "rate": 50,
          "code": "<string>",
          "reason": "<string>"
        }
      ]
    }
  ],
  "allowance_charges": [
    {
      "type": "<string>",
      "amount": 499999999.5,
      "rate": 50,
      "code": "<string>",
      "reason": "<string>"
    }
  ]
}
'

200

{
  "id": "<string>",
  "type": "<string>",
  "origin": "<string>",
  "document_number": "<string>",
  "order_number": "<string>",
  "despatch_reference": "<string>",
  "buyer_reference": "<string>",
  "issue_date": "2023-12-25",
  "due_date": "2023-12-25",
  "tax_point_date": "2023-12-25",
  "delivery_date": "2023-12-25",
  "period_start": "2023-12-25",
  "period_end": "2023-12-25",
  "payment_remittance": "<string>",
  "is_remittance_structured": true,
  "create_date": "2023-11-07T05:31:56Z",
  "currency": "<string>",
  "tax_exclusive_amount": 123,
  "tax_amount": 123,
  "total_amount": 123,
  "paid_amount": 123,
  "remaining_amount": 123,
  "payment_status": "<string>",
  "accounting_status": "<string>",
  "pdf_available": true,
  "xml_available": true,
  "relation_type": "<string>",
  "relation_id": "<string>",
  "journal_id": "<string>",
  "delivery_location_id": "<string>",
  "payment_terms": "<string>",
  "legal_notice": "<string>",
  "peppol_status": "<string>",
  "mail_status": "<string>",
  "attachments": [
    {
      "filename": "<string>",
      "mimetype": "<string>"
    }
  ],
  "allowance_charges": [
    {
      "code": "<string>",
      "type": "<string>",
      "amount": 123,
      "reason": "<string>",
      "rate": 123
    }
  ],
  "lines": [
    {
      "sequence": 123,
      "quantity": 123,
      "vat_rate": 123,
      "item_name": "<string>",
      "item_description": "<string>",
      "unit_price": 123,
      "unit_code": "<string>",
      "vat_code": "<string>",
      "subtotal": 123,
      "total": 123,
      "tax_amount": 123,
      "section_name": "<string>",
      "item_properties": {},
      "item_identification": "<string>",
      "product_code": "<string>",
      "allowance_charges": [
        {
          "code": "<string>",
          "type": "<string>",
          "amount": 123,
          "reason": "<string>",
          "rate": 123
        }
      ]
    }
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

document_uuid · string · required

Body

application/json

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.

type · string | null

Read-only after creation.

journal_id · string | null

Read-only after creation.

paid_amount · number | null

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.

Required range: 0 <= x <= 999999999

relation_id · string | null

Opaque identifier of the third party the document is issued to. It says by itself whether it is a company or a contact.

relation_type · string | null

Ignored: read from relation_id, like at creation.

attachments · any[] | null

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.

issue_date · string<date> | null

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.

due_date · string<date> | null

Ignored: always derived from payment_terms, as at creation.

payment_terms · string | null

Payment terms, as <days>-<basis> (df, fm, mf). Changing them re-derives the due date.

Pattern: ^\d{1,4}-(df|fm|mf)$

delivery_location_id · string | null

One of the third party's saved delivery addresses, or null to detach the one currently set.

tax_point_date · string<date> | null

Date the VAT becomes chargeable.

delivery_date · string<date> | null

Date of the actual delivery — today or earlier, never a future date.

period_start · string<date> | null

First day of the billed period.

period_end · string<date> | null

Last day of the billed period.

order_number · string | null

Order number.

Maximum string length: 255

despatch_reference · string | null

Reference of the despatch advice.

Maximum string length: 50

buyer_reference · string | null

Reference given by the buyer.

Maximum string length: 50

legal_notice · string | null

Legal mention printed at the bottom of the document. null clears it.

Maximum string length: 10000

currency · string | null

ISO 4217 currency code of every amount.

Maximum string length: 20

lines · LineIn · object[] | null

Replaces all the lines of the document. At least one is required — a document without lines is not representable — and 500 at most.

Required array length: 1 - 500 elements

Show child attributes

allowance_charges · AllowanceChargeIn · object[] | null

Replaces all the discounts/surcharges of the document. An empty list removes them.

Maximum array length: 50

Show child attributes

Response

200

application/json

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.

id · string · required

Opaque unique identifier of the document.

type · string · required

Document type. One of: sale_invoice, sale_credit_note, purchase_invoice, purchase_credit_note, other_document, unknown.

origin · string · required

Channel the document came in through. One of: fidly (generated in Fidly), manual, peppol, mail, odoo, billit, api (or unknown).

document_number · string | null · required

The document's own number (e.g. invoice number).

order_number · string | null · required

Purchase/sales order number referenced by the document.

despatch_reference · string | null · required

Reference of the despatch advice (delivery note) related to the document.

buyer_reference · string | null · required

Reference given by the buyer, to be quoted back on the document (e.g. a cost centre).

issue_date · string<date> | null · required

Date the document was issued (ISO YYYY-MM-DD).

due_date · string<date> | null · required

Payment due date (ISO YYYY-MM-DD).

tax_point_date · string<date> | null · required

Date the VAT becomes chargeable, when it differs from the issue date (ISO YYYY-MM-DD).

delivery_date · string<date> | null · required

Date the goods/services were actually delivered (ISO YYYY-MM-DD).

period_start · string<date> | null · required

First day of the period the document bills (ISO YYYY-MM-DD).

period_end · string<date> | null · required

Last day of the period the document bills (ISO YYYY-MM-DD).

payment_remittance · string | null · required

Communication to quote when paying the document. null when the document carries none.

is_remittance_structured · boolean · required

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.

create_date · string<date-time> | null · required

Timestamp the document was created in Fidly (ISO 8601). May be null on rare legacy rows where it was never set.

currency · string | null · required

ISO 4217 currency code of all amounts (e.g. EUR).

tax_exclusive_amount · number | null · required

Total amount excluding tax.

tax_amount · number | null · required

Total tax (VAT) amount.

total_amount · number | null · required

Total amount payable, tax included.

paid_amount · number | null · required

Amount already paid.

remaining_amount · number | null · required

Amount still to be paid (total_amount minus paid_amount).

payment_status · string · required

Payment state. One of: unpaid, partial, paid (or unknown).

accounting_status · string · required

Accounting workflow state. One of: waiting, accepted, transfered, exported, export_error, imported, validated, hidden, exporting, posting, posting_error, deleted (or unknown).

pdf_available · boolean · required

true if a PDF is stored for this document (retrievable via the file endpoint).

xml_available · boolean · required

true if a structured XML version (e.g. Peppol/UBL) is stored for this document.

relation_type · string | null

Nature of relation_id: company (a registered business relation) or contact (an individual contact). null when there is no linked third party.

relation_id · string | null

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.

journal_id · string | null

Opaque identifier of the journal the document is booked in (resolvable via GET /journals/{id}). null when the document has no linked journal.

delivery_location_id · string | null

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 · string | null

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_notice · string | null

Legal mention printed at the bottom of the document (e.g. a VAT exemption wording). Always null on received documents.

peppol_status · string | null

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.

mail_status · string | null

E-mail send state of an issued document. One of: not_sent, sent, failed (or unknown). Always null on a received document.

attachments · AttachmentOut · object[]

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.

Show child attributes

allowance_charges · AllowanceChargeOut · object[]

Discounts/surcharges applied to the document as a whole, after the lines and their own. tax_exclusive_amount is already net of them.

Show child attributes

lines · LineOut · object[]

Detailed lines of the document (invoiced items/services). Empty when none are stored.

Show child attributes