InvoicePilot

What it is

InvoicePilot — the AI invoicing agent for freelancers. Freelancers lose hours to invoicing admin and weeks to late payments. InvoicePilot replaces the whole chore with one sentence. The freelancer types something like: "Logo design for Maria's bakery, $450, due Friday" …and the agent does the rest: it drafts a structured invoice from that sentence, creates and sends a PayPal invoice, tracks it on a dashboard, and — when a client goes quiet — drafts polite, tone-escalating follow-up emails automatically. It is agent-to-human commerce, end to end: the human says what the work was; the agent handles the money paperwork and the awkward chasing.

What was built

• Natural-language invoice drafting — one plain-English sentence (flat-fee or hourly phrasing, weekday / "in N days" due dates) becomes a fully structured invoice draft: client, item, quantity/rate, total, due date.
• PayPal invoice creation + sending — the draft is created and sent through the PayPal Invoicing API v2, returning a payer-view link the client can pay in one click.
• Live dashboard — totals for draft / unpaid / paid / overdue invoices, outstanding vs. collected value, and a per-invoice status list.
• Follow-up agent — overdue detection plus reminder drafts whose tone escalates with age (friendly heads-up → first notice → second notice), each carrying the invoice's payer link.
• Zero-dependency Node app — no build step, no framework; npm start and it runs. Five automated tests cover the parser, the invoice lifecycle, and the agent's summary/follow-up logic (all passing).

How it was built

A small modular Node.js (ES modules) codebase, ~510 lines across five source files, with a swappable payment-gateway interface at its heart:

• src/ai.js — natural language → invoice draft. Uses an OpenAI-compatible model when OPENAI_API_KEY is configured; otherwise a built-in deterministic parser handles flat-fee and hourly shapes, so the demo runs with zero API keys.
• src/paypal.js — the real PayPal REST client (OAuth2 client-credentials; create / send / get / list against Invoicing API v2).
• src/paypalSimulator.js — a faithful offline simulator implementing the exact same gateway interface and lifecycle (DRAFT → UNPAID → PAID).
• src/agent.js — dashboard summaries, overdue detection, and the follow-up drafting agent.
• src/server.js + public/index.html — HTTP API and a one-page UI. The gateway factory picks the real PayPal client automatically when sandbox credentials are present, and the simulator otherwise — nothing else in the app changes between modes.

What I learned

• PayPal's Invoicing API v2 resource model (detail / items / amount / payment terms) and its OAuth2 scope model: authenticating is not the same as being authorized — an app can hold a valid token whose scope does not yet include invoicing.
• Designing an agent around a gateway interface rather than a vendor: when the live scope lagged, the identical simulator kept the whole product demonstrable without a single line of application code changing.
• How much of "AI product" work is deterministic scaffolding: the parser fallback, the lifecycle state machine, and the tone-escalation rules carry the demo even when no LLM key exists.

Challenges faced

• Invoicing scope propagation (resolved): the sandbox app initially authenticated over OAuth2 with the Invoicing feature enabled, but the issued token's scope did not yet include invoicing, so live calls returned 403 NOT_AUTHORIZED. On 2026-11-05 the scope landed (https://uri.paypal.com/services/invoicing) and a full live sandbox flow was verified end to end: the sentence "Logo design for Maria's bakery, $450, due Friday" was AI-drafted (due 2026-11-06), created as a real PayPal sandbox invoice, sent to [email protected], and read back via the list endpoint — invoice INV2-EU5S-QAHL-KY79-NFM8, status SENT, USD 450.00. The demo video was recorded earlier on the built-in simulator — the identical gateway interface and lifecycle, labelled on screen — while the live result above is the real sandbox proof.
• Ambiguous natural language: possessives ("Maria's bakery"), relative due dates ("due Friday", "in 3 days"), and hourly vs. flat phrasings all needed explicit parser rules and tests.
• Keeping the demo honest: the UI labels which gateway is live (simulator vs. real sandbox), so judges always know which mode they are looking at.

Resources / tutorials used

• PayPal Developer documentation — Invoicing API v2 reference and OAuth2 client-credentials guide (developer.paypal.com).
• Devpost / PayPal AI Hackathon rules and submission guide.
• Node.js built-in test runner documentation.

Built With

• javascript
• node.js
• paypal