Invoice Pilot

Inspiration

Freelancers do the work, then spend hours on the part nobody enjoys: writing invoices, wondering who will pay late, and sending awkward follow-ups. We started with one small feature (type what you did, get an invoice) and asked a bigger question: what if AI could handle the whole money-collection loop, not just the first step?

What it does

InvoicePilot is an AI agent that gets freelancers paid.

AI invoice drafting: paste notes, an email or a transcript. Gemini extracts the client, line items, tax, discount and due date. You review and edit, then send it through the PayPal Invoicing API.
Payment-risk radar: before you send, it scores how likely this client is to pay late, explains why, and suggests a deposit, shorter terms or an early-pay offer.
Collections agent: a pre-due nudge, then friendly, firm and final reminders. Gemini writes each one in the right tone and PayPal sends it. Run it on Autopilot or in Review mode, where nothing goes out until you approve.
Cash-flow forecast and "Ask your books": a risk-weighted weekly forecast, and plain-English questions such as "Who is my riskiest client?".
Retainers: recurring invoices that bill themselves weekly, monthly or quarterly.
Instant payment links: a shareable pay page backed by PayPal Orders (create, approve, capture), no invoice needed.
A complete product: accounts, client list, dashboard, PDF and CSV export, status sync by polling and signed webhooks, and an activity log.

How we built it

Backend: Python and Flask, SQLite with versioned migrations, and a background scheduler that syncs PayPal status, bills retainers and runs the agent.
PayPal: Invoicing v2 (generate number, create, send, get, remind, cancel), Orders v2 (create, capture) and webhook signature verification with idempotent event handling.
AI: Gemini through its REST API, used for invoice extraction, reminder writing, risk explanations and Q&A. Every AI feature has an offline fallback, so the app still works without a key.
Frontend: server-rendered pages with vanilla JavaScript, an XSS-safe DOM builder and hand-drawn SVG charts. No framework and no CDN.
Risk model: transparent and explainable, not a black box. For a client with $L$ late (or currently overdue) invoices out of $N$ resolved ones:

$$\text{score} = 100 \cdot \frac{L + 0.8}{N + 2.4} + \text{adjustments}$$

The smoothing means a brand-new client starts near 33% instead of 0% or 100%. The adjustments cover overdue items, typical delay, unusually large amounts and long terms.

Challenges we ran into

Money maths must match PayPal. PayPal applies the discount first and then the tax, per line, so we used exact decimal arithmetic and treat PayPal's total as the source of truth.
Keeping status honest. Payments can arrive by webhook, by polling, or both, so updates are idempotent and duplicate webhook events are ignored.
Testing without live payments. We built an offline PayPal simulator so the whole flow (invoice, pay, remind, order, capture) can be tested in 19 automated tests. It also caught a real bug: holding a database write open during a network call.
Making AI safe to trust with money. The agent never opens with a final notice, spaces reminders out, never invents fees, and lets you approve every message first.

What we learned

Real products need the boring parts done well: security, idempotency, rate limits and migrations.
AI works best when the final send is a human choice.
An explainable score is easier to trust than a clever one.