INSPIRATION
Freelancers and small agencies close deals in WhatsApp chats and DMs, then lose hours turning those chats into invoices and chasing payment. When a job used a helper, such as a designer, a copywriter or a sub-contractor, that person waits until the freelancer remembers to forward their cut. We wanted the whole path from "deal agreed" to "everyone paid" to take one paste and one tap.
WHAT IT DOES
• Reads a pasted client conversation and drafts a PayPal invoice with an LLM: client, email, currency, due date, line items, and helper splits taken from a private note. • Validates the AI's output in code before anything can be sent. Bad emails, past due dates, bad amounts, and splits over 100% go to Needs review. • Keeps a human in control. Nothing is sent until the owner approves, on the dashboard or through a single-use, hashed, 48-hour approval link (a GET never sends). • Creates and sends a real invoice with the PayPal Invoicing API v2. • Marks an invoice paid only when PayPal reports the full amount. Partial payments are tracked separately. • Has the AI write tone-aware reminders for overdue invoices and sends them through PayPal's remind endpoint, at most once every 3 days automatically. • Pays each helper their percentage through PayPal Payouts after full payment, exactly once, because the batch id is fixed per invoice. • Gives the owner an Agent Console built on AG Grid and AG Charts: a money ribbon, a live agent feed, an editable ledger with the agent's next step for each invoice, an invoice preview with PAID and OVERDUE stamps, a money-split bar, a lifecycle timeline, insights, and Autopilot. • Judge Mode: a short guided replay on in-browser demo data that needs no keys and touches no PayPal.
HOW WE BUILT IT
• Backend: Python and FastAPI with SQLite. An events table is the agent's audit log. • AI: an OpenAI-compatible endpoint (NVIDIA API, Nemotron) for extraction and reminder writing, with a regex fallback for "N% to email" splits. • PayPal Sandbox: OAuth2, Invoicing v2 (create, send, get, remind, cancel), and Payouts v1. • Frontend: one dashboard.html using AG Grid Community and AG Charts Community. • Deployed on Render. Tests: an end-to-end test with PayPal and the LLM mocked (draft, review, edit, approve, nudge, partial, full, single payout, cancel), plus a browser test suite for Judge Mode and live mode.
CHALLENGES WE RAN INTO
• PayPal's create-invoice response returns only a link, so the invoice id is parsed from the href. • Payment status can change on partial payments, so we compare paid amount with total before calling an invoice paid. • Making payouts idempotent: a fixed batch id per invoice plus an atomic status claim means a retry can never double-pay. • Reasoning models returned empty content, so we strip think blocks and fall back to the reasoning field. • Several hosted models were retired mid-build, so the AI provider is set by environment variables.
ACCOMPLISHMENTS THAT WE'RE PROUD OF
• The full loop works on the real PayPal Sandbox: an AI-drafted invoice was approved, sent, and paid, and the helper received an automatic 20% payout. • The AI never acts alone. Code validates its work, and a human approves before money moves.
WHAT WE LEARNED
Agentic commerce needs guardrails more than cleverness: deterministic validation, explicit approval, idempotent money movement, and an audit trail of everything the agent does.
WHAT'S NEXT FOR SETTLE
• PayPal webhooks instead of polling, plus scheduled jobs on the host. • Multi-user accounts, recurring retainers, and partial-payment plans. • WhatsApp and email intake, so the agent drafts straight from the conversation.
Built With
- ag-charts
- ag-grid
- fastapi
- javascript
- llm
- nvidia-nim
- paypal
- paypal-invoicing-api
- paypal-payout-api
- python
- render
- sqlite
