Reconcile what has actually been paid

get_payment_status returns amount_paid, balance_due, the payment history and a reconciliation block that compares the ledger total with the stored paid amount. A mismatch is surfaced rather than silently resolved.

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

Who this is for: Anyone answering "who still owes me" for a client, an accountant or a month-end close.
Billr capabilities used: get_payment_statuslist_invoicesget_client

What you need first

An invoice id, or a list of them from list_invoices.
A key with the read scope, which every profile includes.
A tolerance for the answer "the numbers disagree", which is itself useful information.

Step by step

01Read one invoice in detail
get_payment_status returns the invoice summary, every recorded payment with its method and source, and the reconciliation block.
Example
```
get_payment_status  {
  "invoice_id": "6b1f0c62-6a0f-4f38-9d0e-3a1f9a2b7c11"
}
```
02Compare ledger and stored amount
reconciliation.ledger_total is the sum of the payment rows; reconciliation.recorded_amount_paid is what the invoice stores. When mismatch is true, the summary says so and no figure should be quoted until it is checked.
03Find the invoices that are still owed
list_invoices with status: "unpaid" matches sent, viewed, partial and overdue invoices in one call, and each row carries is_overdue plus balance_due.
Example
```
list_invoices  {
  "status": "unpaid",
  "limit": 50
}
```
04Put a client name on it
get_client returns outstanding_balance, total_invoiced and total_paid for one client, which is the number to quote when someone asks "what do I owe you".

Worked example

Fictional account, field names as returned by the server

You say

Has Harbor & Lane paid INV-1150, and what is left?

Your agent calls

get_payment_status { "invoice_id": "6b1f0c62-6a0f-4f38-9d0e-3a1f9a2b7c11" }

Expected response, abridged

{
  "summary": "INV-1150 is partial: $500.00 paid, $1,000.00 still due.",
  "invoice": {
    "status": "partial",
    "currency": "USD",
    "total": 1500,
    "amount_paid": 500,
    "balance_due": 1000,
    "is_overdue": false
  },
  "payments": [
    {
      "amount": 500,
      "payment_date": "2026-10-02",
      "method": "bank_transfer",
      "source": "web"
    }
  ],
  "reconciliation": {
    "ledger_total": 500,
    "recorded_amount_paid": 500,
    "mismatch": false
  }
}

Limits and gotchas

Reconciliation reports a mismatch; it does not repair one. This repository exposes recording payments, not editing or deleting a payment row, so treat a mismatch as something to investigate before recording anything else.
Payment history is capped per call, and payments_truncated tells you when the list was cut short.
Only real payments appear. Stripe test-mode probes are stored in a different table and are never counted.
An estimate has no balance at all; only invoices carry money owed.

Troubleshooting

The summary warns that the ledger does not match: Open the invoice in the app and compare payment rows with the stored amount. Do not quote either figure until they agree.
A payment is missing from the history: Check payments_truncated first, which means the list was cut short. Otherwise the money may have arrived outside Billr, such as a transfer nobody logged; confirm with the client or the bank before recording it, because a duplicate row would inflate the ledger.
An invoice shows overdue but the client says it was paid: Overdue is derived from the status and due date: only sent, viewed and partial invoices can be overdue. If the balance is zero the invoice is paid and no longer overdue, so a remaining overdue state means part of the balance is still recorded as due.

Sources

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