Record a partial payment

record_payment adds an entry to the payment ledger and updates amount_paid and balance_due. The invoice becomes paid when the balance reaches zero and partial when some balance remains.

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

Who this is for: People whose clients pay in instalments, or who receive a deposit before the final invoice balance.
Billr capabilities used: record_paymentget_payment_statusget_invoice

What you need first

An invoice that is not cancelled, with a balance still due.
A key with the billing or full profile: recording payments needs the payments scope.
The amount received, the date, and the method, which must be one of the values the tool accepts.

Step by step

01Check the current balance
get_payment_status returns amount_paid, balance_due and the payment history. Recording against a stale number is the easiest way to end up with a mismatch.

02Record the amount

Amount must be greater than zero. Method accepts cash, check, bank_transfer, credit_card, stripe, paypal or other. A request_id makes the call safe to retry.

record_payment  {
  "request_id": "9c4e1d38-5b7a-4e02-8f61-3a5d9c7b1e40",
  "invoice_id": "6b1f0c62-6a0f-4f38-9d0e-3a1f9a2b7c11",
  "amount": 500,
  "method": "bank_transfer",
  "payment_date": "2026-10-02",
  "reference_number": "WIRE-88213"
}

03Read the new state
The result carries the invoice status and the remaining balance. A USD 1,500 invoice with a 500 payment becomes partial with 1,000 due.
04Know what the client sees
The public invoice page reflects the new balance. Online card payments recorded through Stripe appear in the same history with a stripe source.

Worked example

Fictional account, field names as returned by the server

You say

Harbor & Lane wired $500 against INV-1150 today.

Your agent calls

record_payment { "request_id": "9c4e1d38-5b7a-4e02-8f61-3a5d9c7b1e40", "invoice_id": "6b1f0c62-6a0f-4f38-9d0e-3a1f9a2b7c11", "amount": 500, "method": "bank_transfer", "payment_date": "2026-10-02" }

Expected response, abridged

{
  "summary": "Recorded $500.00 payment on INV-1150. It is now partial with $1,000.00 balance due.",
  "invoice": {
    "status": "partial",
    "amount_paid": 500,
    "balance_due": 1000
  }
}

Limits and gotchas

Recording a payment is bookkeeping, not collection. Billr never touches client funds.
An overpayment is not special-cased; the balance goes to zero and the invoice is marked paid.
Cancelled invoices refuse payments, and the ledger is append-only: corrections belong in the app.
Sandbox test payments from Stripe test mode are stored separately and never appear in this history.

Troubleshooting

"Payments cannot be recorded against it": The invoice is cancelled. Recreate it if the work is still owed, and record the payment against the new document.
The invoice is still partial after the final payment: Compare the amount recorded with the balance due at the time. Use get_payment_status and its reconciliation block to see the ledger total next to the stored paid amount.
The call was retried and the balance doubled: Reuse the same request_id on retries. A new id with the same amount records a second payment.

Sources

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