Inspiration
Freelancers, contractors, and agency founders lose hours every week to administrative billing friction. After putting in long hours of creative or technical work, the last thing anyone wants to do is navigate tedious multi-step invoice forms, look up client details, calculate line-item totals, and manually track payment due dates. Even worse is chasing late payments—drafting uncomfortable reminder emails that risk damaging client relationships.
We asked a simple question: What if sending a legally binding, official PayPal invoice was as quick and natural as typing a single sentence to a colleague?
With the arrival of Google Gemini’s high-precision structured JSON capabilities and PayPal’s Invoicing API v2, we saw an opportunity to bridge the gap between generative AI and mission-critical financial infrastructure. InvoiceFlow AI was created to turn natural language into official, payable PayPal invoices in seconds—letting freelancers focus on their craft, not paperwork.
What it does
InvoiceFlow AI is an intelligent receivables assistant that transforms plain English descriptions into official PayPal invoices:
- 💬 Natural Language Invoicing: Users describe work naturally (e.g., "Invoice Acme Corp ([email protected]) $450 for logo design and $120 for revisions, due in 15 days"). Google Gemini accurately extracts client info, line items, unit rates, quantities, and relative due dates into structured data.
- 🛡️ Zero Floating-Point Financial Math: The LLM is strictly prohibited from calculating money totals. Our server computes all currency operations in integer cents (
lib/money.ts), eliminating arithmetic hallucinations and IEEE 754 floating-point drift. - 💳 Complete PayPal Invoicing v2 Lifecycle: Directly integrates with PayPal's sandbox/live endpoints to generate sequential invoice numbers, create drafts, send invoices with hosted payment links, and track payment statuses.
- 📊 Real-Time Financial Dashboard: Instant visibility into cash flow with 4 live stat cards (Total Invoiced, Paid, Outstanding, Overdue) and an AG Grid data table with multi-column sorting, filtering, and status badges.
- 🤖 Contextual AI Payment Reminders: When an invoice is unpaid or overdue, Gemini crafts personalized reminder emails calibrated to the invoice age and chosen tone (Friendly, Neutral, or Firm). Reminders are dispatched via PayPal only with explicit merchant approval.
- 📈 Executive Business Health Summary: Precomputes financial aggregates server-side and passes verified metrics to Gemini to produce an executive plain-English cash-flow assessment and actionable growth recommendations.
- 🚀 Full Offline Demo Mode: Out-of-the-box sandbox environment with SQLite persistence and a deterministic mock LLM—allowing hackathon judges to test the full flow without needing external API credentials.
How we built it
- Frontend: Next.js 14 App Router, React 18, TypeScript, Tailwind CSS, Lucide React icons, and AG Grid Community for high-performance financial data tables.
- AI Engine: Google Gemini 2.0 Flash (
@google/genaiSDK) utilizing native structured JSON schema mode, prompt-injection isolation boundaries, and automated schema validation. - Payments & Billing: PayPal Invoicing API v2 (
/generate-next-invoice-number,/invoices,/send,/remind,/cancel,/payments) with an in-memory cached OAuth2 token layer. - Local Persistence & Caching: SQLite with WAL mode (
better-sqlite3) to store natural language prompt history, dispatched reminder logs, and SHA-256 hash-cached business health summaries. - Reliability & Validation: Strict Zod validation schemas (
lib/schemas.ts), integer-cents money arithmetic, and exponential backoff retry handling for API resilience.
Challenges we ran into
- Eliminating LLM Math Hallucinations: Large Language Models are known to hallucinate arithmetic sums and subtotals. In financial applications, even a 1-cent rounding error breaks trust. We solved this with a strict architectural boundary: Gemini only extracts atomic quantities and unit rates; our TypeScript engine performs all financial additions and multipliers in integer cents: $$\text{Subtotal (cents)} = \sum_{i=1}^{n} (\text{quantity}_i \times \text{unit_price_cents}_i)$$
- Relative Date Resolution: Translating phrases like "net 30", "in two weeks", or "due next Friday" into accurate ISO 8601 dates required feeding an explicit reference UTC timestamp into the system prompt and enforcing strict regex validation.
- PayPal Invoicing v2 Schema Strictness: PayPal's API requires strict structure (e.g., monetary amounts formatted as exact two-decimal strings, recipient objects, and item arrays). We engineered a resilient data transformation layer that maps Zod-validated payloads into valid PayPal schemas.
- Prompt Injection Defense: Preventing malicious inputs from overriding system instructions by wrapping user-provided billing text in
<user_invoice_description>XML data boundaries.
Accomplishments that we're proud of
- Instant Invoicing Experience: Converting casual, freeform descriptions into official PayPal invoices with active payment links in under 3 seconds.
- 100% Financial Accuracy: Zero floating-point drift or LLM math errors, verified by our Vitest test suite.
- Human-in-the-Loop Safeguards: An intuitive review screen where freelancers can inspect, adjust, or add line items before anything is officially dispatched to PayPal.
- Zero-Friction Demo Mode: Reviewers and judges can test the app immediately without having to configure PayPal Developer sandbox accounts or Gemini API keys.
What we learned
- How to pair Google Gemini's structured output mode with strict Zod schemas for deterministic, production-grade API pipelines.
- Deep hands-on experience with PayPal's Invoicing v2 REST API, OAuth2 caching, and invoice state transitions.
- The power of combining LLMs for unstructured language extraction with traditional deterministic code for mission-critical calculations.
What's next for InvoiceFlow AI
- PayPal Webhooks Integration: Adding real-time webhook listeners (
INVOICING.INVOICE.PAID) for instant dashboard status updates when clients pay on PayPal.com. - Multi-Currency Real-Time Conversion: Real-time FX conversion to display multi-currency earnings in a single preferred dashboard currency.
- Recurring & Retainer Invoices: Scheduled automatic invoice generation for ongoing freelance client retainers.
- Mobile & Messaging Integrations: Enabling freelancers to create and send invoices on the go directly from Slack and WhatsApp.
Built With
- ag-grid
- artificial-intelligence
- fintech
- google-gemini
- next.js
- node.js
- paypal
- react
- rest-api
- sqlite
- tailwindcss
- typescript
- vitest
- zod