How to close out monthly client billing without missing unbilled hours or expenses

A month-end close is not one task, it is five questions asked in an order that makes each answer trustworthy. What is unbilled? Does any of it have nowhere to go? What should be drafted from it? What is late from earlier months? What does the ledger say the month came to?

The order matters because later questions depend on earlier answers. Revenue totals count invoices that have already been issued and exclude the drafts you are about to write, so reading them first answers a different question. Drafting before resolving unassigned work leaves billable time behind. Doing the late-invoice review last, rather than first, keeps reminders from going out on work you have not finished billing.

list_unbilled groups billable time and expenses that are not yet attached to an invoice, by client and currency, and totals each group. The response is paged at 500 rows of time and 500 rows of expenses, and the totals describe the page you asked for.

That last detail is what keeps a close honest. Keep passing next_offset back as offset until it returns null. If either collection filled its page, the response also sets truncated: true and the summary says so, which means the groups you can see are a partial picture.

One thing the tool does not do is filter by month. Every entry comes back with its own date, including work logged in earlier months that was never billed. Selecting the rows you want is a reading step: collect the entries whose date falls inside the month you are closing, note what is older than that, and decide whether this month pays for the carryover or whether it stays for a later conversation.

list_unbilled  { "business_id": "b1f2c3d4-5e67-4a89-9b01-2c3d4e5f6a7b" }
list_unbilled  { "business_id": "b1f2c3d4-5e67-4a89-9b01-2c3d4e5f6a7b", "offset": 500 }

Work through the client groups and draft an invoice for each. Passing time_entry_ids and expense_ids prices the source work and links it in one atomic step, so the entries cannot be billed again by a later invoice.

A client group is keyed on client and currency together, which is why a client billed in two currencies appears twice. Do not merge those groups onto one invoice: create_invoice refuses source work in a currency other than the invoice currency rather than inventing a conversion.

Read every page before this step. Once an entry is attached to a draft it leaves the unbilled list, so a filter or a page you have not read yet is the easiest way to bill an incomplete month. If you do find something after drafting, bill a month of logged work covers the follow-up: correct the draft while it is still a draft.

create_invoice  {
  "request_id": "d5a1c8f3-6b29-4e47-9c15-8f3a2d6b1e90",
  "client_name": "Harbor & Lane",
  "time_entry_ids": ["3f6c1a44-5b2d-4e71-9c08-7a1d3f5b9e22"],
  "expense_ids": ["5e2b8d31-7a4c-4f09-8d6b-1a3e5c7d9f02"]
}
create_invoice  {
  "request_id": "9b4e7c25-1d38-4a60-8f92-5c7e3b1a6d48",
  "client_name": "Northwind Type Co.",
  "currency": "EUR",
  "time_entry_ids": ["8a1f4c72-6d35-4b90-9e28-1c7a5f3d6b04"]
}

Now look backwards. list_invoices accepts the synthetic status unpaid, which matches invoices that are sent, viewed, partial or overdue, and every row comes back with is_overdue already evaluated from its status and due date.

Reading this before reminders is what stops the two most common mistakes: chasing a draft that was never sent, and chasing an invoice that was paid this morning through a channel you have not recorded yet. Older months show up here too, which is why the unpaid list, not the revenue report, is where follow-up work lives. The review overdue invoices guide covers what to do with each row.

Invoices with their real state

Billr demo data, fictional throughout. View full size

list_invoices  { "status": "unpaid", "limit": 50 }

The last step is a check, not a guess. revenue_summary reports invoiced, paid, outstanding and overdue totals for this month, last month, this year or all time, with status counts and a top-five client breakdown.

Two details decide whether the number means what you think it means. Draft and cancelled invoices are excluded, so a draft you just wrote is not in the totals yet. And the period filters on the invoice issue date, not the payment date, so this is money invoiced in the month rather than cash that arrived during it. If you want cash, record the payments and read the payment history instead.

When a business bills in more than one currency, the response switches to a per-currency breakdown instead of a single combined number, because adding EUR to USD would be meaningless.

{
  "summary": "this month (mixed currencies): $1,450.00 invoiced; €550.00 invoiced.",
  "period": "this_month",
  "currency": null,
  "invoiced_total": null,
  "paid_total": null,
  "outstanding_total": null,
  "overdue_total": null,
  "by_currency": [
    {
      "currency": "USD",
      "invoiced_total": 1450,
      "paid_total": 0,
      "outstanding_total": 1450,
      "overdue_total": 1450,
      "top_clients": [
        {
          "name": "Harbor & Lane",
          "invoiced": 1450
        }
      ]
    },
    {
      "currency": "EUR",
      "invoiced_total": 550,
      "paid_total": 0,
      "outstanding_total": 550,
      "overdue_total": 0,
      "top_clients": [
        {
          "name": "Northwind Type Co.",
          "invoiced": 550
        }
      ]
    }
  ],
  "by_status": {
    "sent": 1
  },
  "top_clients": []
}

The month view leaves out anything issued earlier that is still unpaid: INV-1136 and INV-1129 were issued in earlier months, so they only appear when you read the ledger across all time or when you read the unpaid list. Run the same call with period: "all" when you want that reconciliation.

{
  "summary": "all time (mixed currencies): $3,614.00 invoiced; €550.00 invoiced.",
  "period": "all",
  "currency": null,
  "invoiced_total": null,
  "paid_total": null,
  "outstanding_total": null,
  "overdue_total": null,
  "by_currency": [
    {
      "currency": "USD",
      "invoiced_total": 3614,
      "paid_total": 954,
      "outstanding_total": 2660,
      "overdue_total": 2660,
      "top_clients": [
        {
          "name": "Harbor & Lane",
          "invoiced": 2724
        },
        {
          "name": "Larkspur Audio",
          "invoiced": 890
        }
      ]
    },
    {
      "currency": "EUR",
      "invoiced_total": 550,
      "paid_total": 0,
      "outstanding_total": 550,
      "overdue_total": 0,
      "top_clients": [
        {
          "name": "Northwind Type Co.",
          "invoiced": 550
        }
      ]
    }
  ],
  "by_status": {
    "sent": 1,
    "viewed": 1,
    "partial": 1,
    "paid": 1
  },
  "top_clients": []
}

• Revenue totals come from invoices and recorded payments, and the period filters on the invoice issue date. A payment that arrived but was never recorded is still outstanding in the ledger, so record it if you want the figure to be true.
• list_unbilled has no date filter, so the month boundary is a selection you make from each entry's date. Older unbilled work is visible on every run until somebody bills it or marks it non-billable.
• Currency conversion is not implemented. Per-currency reporting is the honest way to read a mixed ledger.
• A client group with no client attached is surfaced as unassigned work rather than silently billed to anyone.
• The month is an accounting shape you choose. Billr reports on issue dates and due dates; it does not decide when your month closes.