Inspiration
Freelancers rarely get paid in one go. A typical deal is "half upfront, half on delivery", agreed in a chat message. Turning that message into invoices means retyping the terms, remembering which instalment is due, and later writing the hardest email in freelancing: the payment reminder. Write it too soft and it's ignored. Write it too harsh and you lose the client.
I wanted an assistant that does the paperwork and the awkward writing, without ever acting on its own. AI is good at reading a messy deal description. It should not be the one deciding to bill someone or pressure them. So Cadence is built around one rule: the AI proposes, the freelancer approves.
What it does
- Plain words → payment plan. Paste a deal like "Mobile app design for Riverside Dental, priya@…, $1,500: 60% upfront, 40% in 30 days." The AI extracts the client, email, total and instalments with due dates. If the email or amount is missing, it's flagged, never guessed. An email only counts if it appears word for word in your text.
- Review, edit, approve. Change any instalment's name, amount, due date or the note printed on the PayPal invoice. A preview shows exactly what the client will receive.
- Approval gate. Every send (the plan, the next instalment, a reminder) goes through a confirm dialog showing the amount and recipient. The server independently rejects any send without an explicit
approved: true. - Real PayPal invoices. Each instalment becomes a PayPal invoice through the Invoicing API (sandbox). Later instalments are sent one at a time when you choose.
- Live ledger. An AG Grid ledger shows every instalment with its status fetched live from PayPal (Sent, Paid, Overdue, Not sent). It supports sorting, column filters, quick search, a status filter, pagination and CSV export, plus dashboard totals for outstanding, paid and overdue.
- AI reminder strategist inside an escalation policy. For an unpaid invoice, the AI suggests a tone, explains why using the actual numbers ("10 days overdue with 0 reminders sent…"), drafts a short message and recommends a next step. The tone rules are enforced in code, not just requested in the prompt:
- 0–5 days overdue → at least friendly; 6–14 → at least firm; 15+ → formal.
- A stricter tone is allowed only after 2 or more reminders.
- If the AI picks the wrong tone, the code corrects it, labels the change, and rewrites the message to match.
- Messages mentioning late fees, interest, penalties or legal action are rejected, and messages must be under 90 words.
- Audit trail. A timeline of approvals, invoices sent, reminders and payments.
How I built it
- PayPal Invoicing API v2 (sandbox): OAuth client-credentials tokens (cached until 60 seconds before expiry), create draft invoice, send, get (for live status), send reminder, and record payment (used only by a clearly labelled "Simulate payment" demo button).
- AI: a small provider layer that speaks the OpenAI-compatible Chat Completions format, so any compatible provider plugs in. Groq (
gpt-oss-120b) is the primary. Google Gemini is the fallback, used automatically when the primary returns a rate limit, a server error or takes longer than 45 seconds. Every AI answer is requested as JSON with the exact shape in the prompt, then validated. A malformed answer is retried once. Request parameters are set per provider, according to each provider's docs. - Backend: Node.js and Express. Deals are stored as a small JSON file, while invoice status always comes from PayPal, which is the source of truth.
- Frontend: plain HTML, CSS and JavaScript, with no framework and no CDN. AG Grid Community powers the ledger and is served from the app itself. All user and AI text is rendered with
textContent, neverinnerHTML. - Deployment: Render web service.
- Built with Kiro, an AI coding assistant, which I used for implementation, testing scripts and docs.
Challenges I ran into
- PayPal regional rules. My first test invoice failed with
INR_FOREIGN_CURRENCY_BLOCKED, because PayPal doesn't allow India-registered accounts to invoice recipients in India. I set up sandbox accounts that work for USD invoicing. - A stale OAuth token. After enabling Invoicing on my sandbox app, every call still returned
NOT_AUTHORIZED. PayPal kept handing back the old cached token, which had no invoicing permission. Revoking it with/v1/oauth2/token/terminatefixed it, and I learned to check token scopes instead of guessing. - Keeping AI providers reliable on free tiers. Along the way I hit an invalid key, a provider spend limit and a network-level "Access denied". That's why the AI layer is provider-agnostic, with a timed fallback and per-provider parameters.
- The AI kept being too polite. In testing, the model chose "friendly" even at 25 days overdue. Prompting alone didn't fix it reliably, so I moved the escalation policy into code and let the AI work inside it.
- Making the AI unable to invent facts. Models will fill in a plausible email address if you let them. Cadence checks extracted emails against the original text and validates amounts, currency and schedules on both the client and the server.
- Deployment details. The app first listened only on localhost, which Render can't reach. AG Grid's package exports also hid the browser bundle from Node's resolver. Both needed small, deliberate fixes.
Accomplishments that I'm proud of
- A real end-to-end flow, not a mock. Every invoice in the demo is a real PayPal sandbox invoice, created, sent, reminded and tracked through the Invoicing API.
- Human-in-the-loop by design. The approval rule is enforced twice: in the UI with a confirm dialog that shows the amount and recipient, and on the server, which rejects anything without explicit approval. I tested that rejected requests send nothing.
- AI that is useful and still constrained. The reminder strategist explains its reasoning with real numbers, and code-level guardrails mean it can't escalate too early, threaten, or invent fees.
- A product, not a proof of concept. Editing before approval, a preview of what the client receives, a ledger with live status, loading, empty and error states, and an audit trail.
What I learned
- The most valuable thing AI can do in payments is structure and draft, not decide. Splitting "AI proposes" from "human approves" made the product simpler and more trustworthy.
- Prompts are guidance, but policy belongs in code. Anything that must always hold (tone escalation, no invented fees, word limits, valid amounts) is checked after the model answers.
- PayPal's Invoicing API covers the whole invoice lifecycle, but real-world details (token scopes, regional rules, reminder limits) matter as much as the endpoints.
What's next for Cadence
These are plans, not current features:
- Automatic overdue detection and payment updates with PayPal webhooks (for example
INVOICING.INVOICE.PAID), instead of entering days overdue by hand. - Real accounts so each freelancer connects their own PayPal business account, moving from sandbox to production.
- Editing unsent instalments after approval, and a persistent database instead of a JSON file.
- Reminder scheduling that suggests when to send the next reminder, still with approval before anything goes out.
Built With
- ag-grid
- css3
- express.js
- gemini
- gpt-oss
- groq
- html5
- javascript
- kiro
- node.js
- oauth2
- paypal
- paypal-invoicing-api
- render
- rest-api