Review revenue and what is still outstanding

revenue_summary reports invoiced, paid, outstanding and overdue totals for one business over this month, last month, this year or all time, with status counts and the top five clients. Draft and cancelled invoices are excluded from the money totals.

Written and reviewed by the Billr team. Published 2026-09-20, last reviewed 2026-09-20.

Who this is for: Anyone closing a month, checking a quarter, or answering "how is the business doing" from real invoices.
Billr capabilities used: revenue_summarylist_invoicesget_client

What you need first

Invoices in the business, ideally more than one month of them.
A key with the read scope, which every profile includes.
A business id if the key covers more than one business.

Step by step

01Pick the period deliberately
The period matches against each invoice issue date, and this_year is the default. Use all when you want the lifetime picture.
Example
```
revenue_summary  {
  "period": "this_month"
}
```
02Read the four totals
invoiced_total is what was billed, paid_total is what landed, outstanding_total is what is still due, and overdue_total is the part of outstanding that is past due. Overdue is a subset, not an addition.
03Check the status counts
by_status counts every invoice in the period including drafts and cancelled ones, which are excluded from the money totals. That difference is why the counts can look higher than the totals imply.
04Handle mixed currencies honestly
When one business has invoices in more than one currency, the summary returns by_currency with per-currency totals and nulls for the combined fields. Billr never adds currencies together.
Example
```
revenue_summary  {
  "period": "all"
}
```

Worked example

Fictional account, field names as returned by the server

You say

How did September look, and who are the biggest clients?

Your agent calls

revenue_summary { "period": "this_month" }

Expected response, abridged

{
  "summary": "this month: $12,400.00 invoiced, $9,100.00 paid, $3,300.00 outstanding ($1,120.00 overdue).",
  "period": "this_month",
  "currency": "USD",
  "invoiced_total": 12400,
  "paid_total": 9100,
  "outstanding_total": 3300,
  "overdue_total": 1120,
  "by_status": {
    "draft": 1,
    "sent": 2,
    "viewed": 1,
    "partial": 1
  },
  "top_clients": [
    {
      "name": "Harbor & Lane",
      "invoiced": 4600
    }
  ]
}

Limits and gotchas

Drafts and cancelled invoices are counted in by_status but excluded from every money total.
A period filter uses issue dates, not payment dates, so a late payment still belongs to the month it was invoiced.
top_clients covers the top five by invoiced amount and is empty on a mixed-currency business.
Long histories are truncated at the reporting limit, and the summary says so when that happens.

Troubleshooting

The totals are null: That business has invoices in more than one currency, so totals are per currency. Read by_currency, or filter the period to see whether the mix disappears.
Outstanding looks higher than the invoices you remember: Partial payments leave a balance on the invoice. Read the rows with list_invoices and status: "unpaid" to see the individual balances.
A client is missing from the top list: The list covers the top five for that period. Use get_client for one client rollup regardless of ranking.

Sources

Reviewed 2026-09-20 against Billr's own tool implementations and the client documentation linked above.