Ledgerbird

Inspiration

Freelancers lose real money to late payments — not because clients refuse to pay, but because chasing is awkward, so it doesn't happen. Invoicing tools are good at sending invoices; nobody helps with the part after the due date, where the relationship matters as much as the amount.

What it does

• Bill from a conversation. Paste the email or chat where a client agreed to work. The agent extracts client, line items, rates, quantities, currency and terms, and creates a PayPal draft invoice.
• A collections queue ranked by risk. Each open invoice gets a 0–100 score from days overdue, amount, and that client's own history with you (on-time rate, average days late).
• Reminders written for the relationship. A reliable long-time client four days late gets a warm nudge; a repeat late payer three weeks over gets a firm note with a date; a client who has gone quiet gets a polite final notice.
• Human in the loop. Anything that emails a client — send, remind, cancel — lands in an approval queue. One click and PayPal sends it with a pay link. An Autopilot switch lets the agent act directly.
• Ask anything: "Who owes me money?", "Chase everyone overdue", "Tom paid by bank transfer, record it", "Cash-flow summary".
• Live payments. A signature-verified PayPal webhook updates the board when a client pays.

How we built it

• PayPal Invoicing v2 is the system of record — Ledgerbird has no database. We use generate-next-invoice-number, create draft, send, remind, cancel, delete, record external payment, list and show invoice details, plus Webhooks with verify-webhook-signature (INVOICING.INVOICE.PAID/UPDATED/CANCELLED/REFUNDED), all against the sandbox with OAuth client credentials.
• AI: a tool-calling agent over seven PayPal tools (get_ledger, create_invoice_draft, send_invoice, send_reminder, record_offline_payment, cancel_invoice, delete_draft). Client-facing tools are intercepted into approval cards unless Autopilot is on. Model: Google Gemini via its OpenAI-compatible endpoint, with automatic fallback when a model is overloaded.
• Risk & tone engine: deterministic Python (app/ledger.py) computes per-client payment profiles from PayPal history and picks the reminder tone the model must follow — the AI writes, the numbers decide.
• Stack: FastAPI, vanilla JS/CSS (no build step), hosted on Render.

Challenges we ran into

• The invoice list endpoint returns summaries without payment transactions, so "days to pay" was always zero; we fetch full details concurrently and cache invoices that can no longer change.
• Back-dated invoices were essential for a realistic demo of overdue accounts; the sandbox accepts past invoice and payment dates, so the seed script recreates months of client history.
• Keeping an autonomous agent safe around client email: we made approval the default and Autopilot opt-in.

Accomplishments that we're proud of

The agent is grounded entirely in live PayPal data, and every action it takes is a real PayPal API call you can see in the sandbox.

What we learned

Most of the value in collections is judgement — who to chase, when, and how — not the email itself. Putting the judgement in transparent code and the wording in the model works better than asking the model to do both.

What's next

Scheduled follow-ups, partial-payment plans, multi-currency reporting, and PayPal Payouts for paying subcontractors when a client's invoice clears.

Tools used

• PayPal Invoicing v2 REST API — create/send/remind/cancel/record payments; source of truth for all data.
• PayPal Webhooks — real-time paid/updated/cancelled events, verified with verify-webhook-signature.
• PayPal sandbox — business account with seeded demo clients.
• Google Gemini (OpenAI-compatible API) — tool-calling agent, invoice extraction, reminder writing.
• Render — hosting (sponsor tool).

Try it

• Live demo: https://ledgerbird.onrender.com (free instance; first load can take ~50 s)
• Code: https://github.com/greatgeekgrace/ledgerbird

Testing instructions

Open the live demo: the board is pre-populated with sandbox clients who pay on time, pay late, or have gone quiet. Try "Who owes me?", "Chase overdue" (then Approve one card), and "Bill from an email" followed by "send it". Everything runs on the PayPal sandbox; no real money moves.

Built With

• fastapi
• gemini
• javascript
• paypal
• paypal-invoicing-api
• paypal-webhooks
• python
• render