Reports

Four reports, read-only: Income, Reported VAT, Overdue and a Client’s Statement. Each is the figure Essentio’s dashboard and its Statement of Account show for the same period, computed by the same code. Every Role may read them, a Viewer’s key included.

How the figures are counted

Money is a string. Every amount is an exact decimal at its currency’s scale — "1190.00", "-57.00" — never a floating-point number. Parse it with a decimal type.
On issue. Income and Reported VAT count a document in the period it was issued in, in full, paid or not. A month that has closed never changes.
A Credit Note subtracts from Income and Reported VAT, and is a credit on a Statement. It is never Overdue.
A Proforma is not a VAT document. It is in no VAT figure. In Income, a Proforma never converted into an Invoice counts only by the share of it that has been paid, so an unpaid one adds nothing; a converted one is counted through its Invoice.
One currency at a time. Income, Reported VAT and Overdue are stated in the Business’s reporting currency. Documents in any other currency are never converted or summed in: other_currency_documents says how many were left out. A Statement has one block per currency.
Drafts and cancelled documents are in no report.
A period is from and to, two days written as YYYY-MM-DD, both included. A missing or malformed day, or a to before from, is a 422 with error.type invalid_request.

GET/v1/reports/income

Income

The net amounts of the documents issued in the period, with the VAT beside it. The dashboard’s Income tab shows this for last year and for this year to date.

Query

Name
from
Type
date
Description
The period’s first day, YYYY-MM-DD.
Name
to
Type
date
Description
The period’s last day, YYYY-MM-DD, not before from.

Answer

Name
currency
Type
string
Description
The Business’s reporting currency.
Name
income
Type
amount
Description
Net of VAT. Invoices in full, Credit Notes subtracted, Proformas by their paid share.
Name
vat
Type
amount
Description
The VAT of the same Invoices and Credit Notes. A Proforma carries none.
Name
other_currency_documents
Type
integer
Description
Documents issued in the period in another currency, left out of both figures.

Request

GET/v1/reports/income

curl -G https://api.essentio.pro/v1/reports/income \
  -H "Authorization: Bearer ess_your_api_key" \
  -d from=2026-08-01 \
  -d to=2026-08-31

Response

{
  "currency": "EUR",
  "from": "2026-08-01",
  "to": "2026-08-31",
  "income": "925.00",
  "vat": "143.00",
  "other_currency_documents": 1
}

GET/v1/reports/vat

Reported VAT

The VAT of the Invoices and Credit Notes issued in the period, split as a VAT return is: by VAT category and rate. The dashboard’s VAT tab shows this month by month.

Query

Name
from
Type
date
Description
The period’s first day, YYYY-MM-DD.
Name
to
Type
date
Description
The period’s last day, YYYY-MM-DD, not before from.

Answer

Name
currency
Type
string
Description
The Business’s reporting currency.
Name
net
Type
amount
Description
The net amount the VAT is on.
Name
vat
Type
amount
Description
The VAT.
Name
bands
Type
array
Description
The same by VAT category and rate, highest rate first: category (the EN16931 code — S, Z, E, AE, K, G, O), rate to two decimals (5.50 is never 6), net and vat. Each 0% category is a band of its own.
Name
other_currency_documents
Type
integer
Description
Invoices and Credit Notes issued in the period in another currency, left out.

Request

GET/v1/reports/vat

curl -G https://api.essentio.pro/v1/reports/vat \
  -H "Authorization: Bearer ess_your_api_key" \
  -d from=2026-08-01 \
  -d to=2026-08-31

Response

{
  "currency": "EUR",
  "from": "2026-08-01",
  "to": "2026-08-31",
  "net": "900.00",
  "vat": "143.00",
  "bands": [
    { "category": "S", "rate": "19.00", "net": "700.00", "vat": "133.00" },
    { "category": "S", "rate": "5.00", "net": "200.00", "vat": "10.00" }
  ],
  "other_currency_documents": 1
}

GET/v1/reports/overdue

Overdue

What Clients owe late, as of today: issued Invoices, and Proformas never converted, past their due date and neither paid nor cancelled. The figures are the dashboard’s Overdue ones. It takes no period: Overdue is where documents stand now.

Answer

Name
currency
Type
string
Description
The Business’s reporting currency.
Name
as_of
Type
date
Description
The day, in UTC, the documents were judged on.
Name
count
Type
integer
Description
The Overdue documents in the reporting currency.
Name
amount_due
Type
amount
Description
What is still owed on them: their Total less what has been paid.
Name
clients
Type
array
Description
The same by Client, largest first: client_id, name, documents and amount_due.
Name
other_currency_documents
Type
integer
Description
Overdue documents in another currency, left out of count and amount_due.

Request

GET/v1/reports/overdue

curl https://api.essentio.pro/v1/reports/overdue \
  -H "Authorization: Bearer ess_your_api_key"

Response

{
  "currency": "EUR",
  "as_of": "2026-09-27",
  "count": 3,
  "amount_due": "2428.00",
  "clients": [
    { "client_id": 42, "name": "Northwind Studio", "documents": 2, "amount_due": "1476.00" },
    { "client_id": 57, "name": "Harbour Café", "documents": 1, "amount_due": "952.00" }
  ],
  "other_currency_documents": 1
}

GET/v1/reports/statement

Statement

A Client’s account for a period: the balance brought forward from the day before it began, every document (on its issue date) and every Payment (on its payment date) dated in the period — whichever document the Payment settles — and the balance on its last day. It is the Statement of Account the Business prints for the same period, one block per currency. A Client of another Business, or none, is a 404.

Query

Name
client_id
Type
integer
Description
The Client’s id.
Name
from
Type
date
Description
The period’s first day, YYYY-MM-DD.
Name
to
Type
date
Description
The period’s last day, YYYY-MM-DD, not before from.

Answer

Name
currencies
Type
array
Description
One block per currency with an entry in the period or a balance brought into it, the currency with most documents first: currency, opening_balance, closing_balance and lines. A negative balance is owed to the Client.
Name
lines
Type
array
Description
Every entry, by date: date, kind (document or payment), document_type (invoice, proforma, credit_note, or null for a Payment), number (a Payment’s reference, - when it has none), description, debit, credit, the running balance, and prepaid — a Payment made on the Proforma the Invoice was converted from.

Request

GET/v1/reports/statement

curl -G https://api.essentio.pro/v1/reports/statement \
  -H "Authorization: Bearer ess_your_api_key" \
  -d client_id=42 \
  -d from=2026-08-01 \
  -d to=2026-08-31

Response

{
  "client_id": 42,
  "from": "2026-08-01",
  "to": "2026-08-31",
  "currencies": [
    {
      "currency": "EUR",
      "opening_balance": "476.00",
      "closing_balance": "1476.00",
      "lines": [
        {
          "date": "2026-08-10",
          "kind": "document",
          "document_type": "invoice",
          "number": "INV-0042",
          "description": "Website redesign",
          "debit": "1190.00",
          "credit": null,
          "balance": "1666.00",
          "prepaid": false
        },
        {
          "date": "2026-08-25",
          "kind": "payment",
          "document_type": null,
          "number": "BANK-8812",
          "description": "Bank Transfer",
          "debit": null,
          "credit": "190.00",
          "balance": "1476.00",
          "prepaid": false
        }
      ]
    }
  ]
}