Inspiration
Freelancers and small businesses do not lose money because they cannot send invoices. They lose time deciding who to chase, writing the same awkward reminder, and reconstructing what happened afterward.
I wanted to build an agent that does the analytical work — reading invoice data, ranking priorities, drafting a contextual reminder — while making it structurally impossible for the AI to quietly email a customer. That tension between useful automation and human control became PayPilot.
What it does
PayPilot is an AI accounts-receivable workspace for PayPal invoices.
It connects to PayPal Sandbox, retrieves real invoices, and shows outstanding, overdue, paid-this-month, and due-in-seven-days totals. Overdue status is derived locally from the due date and shown next to the raw PayPal status.
The AI agent answers questions such as “who owes me the most?” or “draft reminders for overdue invoices” by calling typed tools. It can read invoice facts, calculate cash flow, rank overdue accounts with an explainable heuristic, and create a reminder draft.
A draft is stored as PENDING_APPROVAL. Nothing is sent. The owner can edit the subject and message, approve it, and only then does the server call PayPal’s reminder endpoint. The result shown in the UI comes from the actual PayPal response.
Verified PayPal webhooks update the invoice cache and appear in the activity timeline. Demo data, real sandbox data, and local test fixtures are labelled differently throughout the product.
How I built it
- Next.js 16 App Router, React 19, TypeScript, and Tailwind CSS
- SQLite through
better-sqlite3, with a small service layer separating persistence from business logic - Anthropic Claude with tool use for the agent
- PayPal Invoicing REST API v2 and PayPal webhooks
- Zod for tool and request validation
- Vitest for unit and integration tests
The PayPal client handles OAuth token caching, timeouts, normalized errors, and PayPal-Request-Id for safe write retries. Invoice list and detail responses are normalized into one internal type.
The AI has five tools: four read-only tools for invoice summaries, details, overdue prioritization, and cash flow, plus a draft-only tool that creates a pending approval record. There is deliberately no execution tool. The agent loop is bounded to five rounds, and every tool argument is validated server-side.
Priority scoring is deterministic, not machine learning:
amount (0–40) + days overdue (0–35) + urgency (0–15) + data confidence (0–10)
Every score ships with a sentence explaining it.
Approval is a server-enforced state machine:
PENDING_APPROVAL → APPROVED → EXECUTED or FAILED
The PayPal reminder is only attempted after the approved transition. Execution re-fetches the invoice, re-checks eligibility, uses an idempotency key, and prevents duplicate sends. Failures are terminal and are shown with PayPal’s actual reason.
Challenges I ran into
Webhook payload shape. PayPal Invoicing events nest the invoice as resource.invoice.id, not resource.id. My first verified events were stored but did not update an invoice. I caught this during live sandbox testing, fixed the extraction, and added a regression test.
Sandbox event subscriptions. Individual invoicing event subscriptions did not deliver in this sandbox account. Switching the same webhook to the wildcard * subscription made CREATED, UNPAID, and PAID events arrive and verify correctly. The app safely ignores non-invoice events.
Signature verification. Webhook handling needed the raw request body, the PayPal transmission headers, and the registered webhook ID. Unverified events are rejected, not processed “best effort.” Event IDs are unique, so retries acknowledge duplicates without double-processing.
PayPal ignores custom reminder text. The reminder endpoint sends PayPal’s own system email and does not honor caller-supplied subject or note text. Rather than pretend otherwise, PayPilot keeps the personalized draft as the approval record and explains the limitation in the UI.
Backdated due dates. PayPal may reject past due dates when creating invoices. The seeding script detects the rejection and reports it instead of relabelling a non-overdue invoice. The app never invents invoice status.
Demonstrating honestly. It is easy to make a dashboard look alive with fake data. I made demo mode explicit, labelled every demo row, and made demo execution record a clearly labelled local action instead of claiming a PayPal send.
What I learned
Human approval belongs in the server state machine, not in a disabled button.
Deterministic business logic should stay outside the language model. The model is good at interpreting intent and writing prose; it should not own arithmetic, status transitions, or access to the payment client.
Provider behaviour is the source of truth. Real sandbox testing exposed webhook and reminder details that documentation alone would not have surfaced.
Idempotency is a product feature, not an implementation detail. A user double-clicking “send” should not create two customer emails.
What is real vs. demo
- Demo mode uses five clearly labelled fictional invoices and works from a clean clone.
- Sandbox mode reads real PayPal Sandbox invoices and can execute a real PayPal reminder after approval.
- Local payment simulation is labelled “Local test — not PayPal,” never presented as a webhook.
- No transfers, refunds, payouts, or autonomous reminders are implemented.
Live sandbox verification included a real reminder accepted by PayPal with HTTP 204, and signature-verified webhook deliveries that updated invoice state.
What's next
- Authentication and multi-tenant account scoping
- Postgres and a permanent hosted webhook endpoint
- A real email/SMS provider so the owner’s personalized reminder text is actually delivered
- Invoice creation and more PayPal lifecycle events
- Saved conversations and richer cash-flow scenarios
Built With
- anthropic-claude
- better-sqlite3
- claude-sonnet-5.5
- lucide
- next.js
- node.js
- paypal-invoicing-api
- paypal-sandbox
- paypal-webhooks
- react
- sqlite
- tailwind-css
- typescript
- vitest
- zod
