Inspiration
Freelancers and solo operators often receive invoice details as informal messages, then manually copy names, emails, amounts, dates, and services into a payment dashboard. That process is repetitive and can cause costly mistakes.
What InvoiceFlow Does
InvoiceFlow converts a natural-language request such as:
Invoice Priya at [email protected] for $750 branding design, due in 7 days.
into a structured, editable invoice draft.
The workflow is:
- The user describes the invoice in plain language.
- Google Gemini extracts the recipient, email, line items, currency, and due date.
- Node.js and Zod validate the extracted data.
- The user reviews and edits the invoice.
- Missing or ambiguous information is clearly flagged.
- Only after explicit confirmation does the server create a PayPal Sandbox draft invoice.
InvoiceFlow never invents missing email addresses, silently rounds unsupported monetary precision, or creates drafts from incomplete required fields.
PayPal and AI Usage
- Google Gemini API: Extracts structured invoice data from natural language, resolves relative dates, and identifies missing or ambiguous fields.
- PayPal Sandbox and Invoicing API v2: Uses OAuth authentication to create draft invoices after human review and confirmation.
- Node.js: Powers the HTTP server, API routes, and frontend serving.
- Zod: Validates currency, email addresses, dates, amounts, quantities, and line-item limits.
The application visibly operates in PayPal Sandbox mode. It creates draft invoices only; no real payment is processed and invoices are not automatically sent.
Safety and Human Review
AI output is treated as a draft, not as an instruction to make a financial action. The user can edit every extracted field, and the confirmation action is blocked when required information is missing or invalid. The server validates the invoice again before contacting PayPal.
The project also rejects unsupported currencies, negative or refund amounts, tax and discount transformations, processing fees, malformed emails, excessive decimal precision, and requests containing more than three line items.
What I Learned
This project helped me learn how to combine a generative AI API with deterministic validation and a real payment-platform API. I learned about REST APIs, OAuth client-credentials authentication, environment variables, structured JSON extraction, schema validation, error handling, and human-in-the-loop financial workflows.
Challenges
The main challenges were making AI output reliable enough for financial data, handling missing and ambiguous information, preventing prompt-injection-style instructions from changing the invoice, and ensuring stale data from a previous invoice could not remain in the form. These were addressed with input guards, strict schema validation, regression tests, and explicit frontend state clearing.
Results and Limitations
The repository contains 131 passing automated tests across 19 suites. A recorded run of the authored extraction evaluation achieved 29/30 overall, 19/20 on the development set, 10/10 on the held-out set, and 6/6 clarification accuracy. These are internally authored tests, not an independent benchmark.
InvoiceFlow is a hackathon proof of concept. It is PayPal Sandbox-only, supports USD and up to three line items, creates drafts rather than real transactions, and does not claim perfect accuracy on arbitrary language.
Links
- Source code: https://github.com/eternal-kernel/invoiceflow
Built With
- google-gemini
- javascript
- node.js
- paypal
- paypal-sandbox
- rest-api
- zod
