Invoice Copilot

Late-paying clients? Our AI invoices on PayPal, decodes their excuses, sends firmer reminders as days pass, and still asks YOU before touching money. Made for freelancers. Speaks Hinglish too.

Comment

Invoice Copilot – AI-Powered Invoice & Payment Collection Agent

Inspiration

Freelancers often complete their work successfully but spend hours chasing payments. Creating invoices, tracking unpaid bills, remembering payment deadlines, and drafting reminders that are polite yet effective can become repetitive and uncomfortable, especially when dealing with international clients.

In India, collecting pending payments is commonly called Vasooli. This inspired me to build Invoice Copilot, an AI-powered agent that handles invoice management and payment follow-ups while keeping users in control of every financial action.

The hackathon theme of putting AI behind the wheel of payments raised an important question: How much autonomy should an AI agent have when handling financial workflows?

That question became the foundation of Invoice Copilot: an intelligent payment assistant that automates repetitive tasks without compromising user control, transparency, or security.

What It Does

Invoice Copilot is an AI-powered payment management agent built on the PayPal Invoicing API.

  • Chat-to-Invoice: Create invoices using natural language. For example, "Create an invoice for Rahul Sharma, [email protected], $400 for logo design, due in 10 days." It supports English, Hindi, and Hinglish. If information is missing, the agent asks follow-up questions.
  • Human Approval Before Execution: Every invoice, payment reminder, and saved payment promise appears as a review card. No action is executed until the user confirms it.
  • Payment Tracking & Q&A: Ask questions like "Who hasn't paid me yet?" and get answers based on live PayPal data.
  • Promise-to-Pay Tracker: Convert client messages such as "Sorry yaar, Friday tak pay kar dunga" into structured payment promises. Reminders are paused while a promise is active. If the promised date passes without payment, the promise is marked as broken and the next reminder uses a firmer tone.
  • AI Autopilot: A background agent identifies overdue invoices, generates context-aware reminders, and either requests user approval or sends reminders automatically within configurable limits. Every action is recorded in an audit log.
  • MCP Server Integration: Allows external AI agents, including Claude Desktop, to access invoice management tools while enforcing server-side security limits.
  • Financial Insights Dashboard: Displays cash-flow insights, collection rates, and AI-generated summaries.
  • Voice & Sharing: Supports voice input in English and Hindi, WhatsApp invoice sharing, and QR codes for convenient client payments.
  • Live Payment Updates: Uses PayPal webhooks with a polling fallback to keep invoice statuses updated.

Intelligent Reminder Escalation

Invoice Copilot automatically adjusts the reminder tone based on the number of overdue days:

  • 0–7 days: Friendly reminder
  • 8–21 days: Firm but polite reminder
  • More than 21 days: Firm and final reminder

Collection Rate

The dashboard calculates the payment collection rate using the following formula:

Collection Rate (%) = (Amount Paid / Total Invoiced) × 100

How I Built It

  • Backend: Developed using Python and FastAPI. The paypal_client.py module handles OAuth authentication with token caching, invoice operations, reminders, transactions, disputes, and webhook signature verification.
  • AI Agent: Implemented an LLM-powered agent using tool calling with create_invoice, list_invoices, search_transactions, send_reminder, record_promise, and get_disputes. Used gpt-oss-120b through Groq's OpenAI-compatible API, allowing the model provider to be changed through environment variables.
  • Human-in-the-Loop Architecture: Financial and client-facing actions are prepared by the AI agent but executed only after explicit user confirmation through the frontend.
  • Input Validation: Used Pydantic to validate extracted information, including client names, email addresses, invoice amounts, currencies, and dates before making PayPal API calls.
  • Autopilot Engine: Implemented an asynchronous background process with an approval queue, invoice-level cooldowns, per-run reminder limits, configurable auto-send amount caps, and execution locks. A template-based reminder system acts as a fallback if the AI model fails.
  • Promise Parsing: The AI extracts structured payment information from natural-language messages, including promised dates, summaries, and payment intent such as will_pay or dispute. The backend validates dates before saving promises.
  • MCP Server: Built using the official MCP Python SDK. Enforced restrictions directly inside the server, including maximum invoice amounts, daily action limits, reminder cooldowns, and placeholder-text validation.
  • Frontend: Developed a single-page application using HTML, CSS, and JavaScript, with the Web Speech API for voice interaction.
  • Deployment: Deployed on Render, with source code maintained in a public GitHub repository.

Challenges I Ran Into

  • PayPal Authorization Errors: Initially encountered 403 NOT_AUTHORIZED errors despite using valid credentials. The issue was caused by missing Invoicing permissions and incorrectly configured sandbox accounts. Creating a fresh US Sandbox Business account and application resolved the issue. I also learned that cached access tokens retain previous permissions, requiring a server restart after configuration changes.
  • Invoice Identifier Mismatch: Reminder requests initially failed with 404 errors because the AI passed the short invoice number (e.g., 0006) instead of PayPal's internal invoice ID (e.g., INV2-...). I solved this by implementing backend lookup logic to resolve both formats to the correct internal ID.
  • Webhook Configuration: PayPal webhooks were reaching the root endpoint instead of /webhooks/paypal, resulting in 405 errors. Using the ngrok request inspector helped identify the incorrect endpoint configuration. I also implemented polling as a fallback.
  • Unstable AI Model Providers: Faced model retirement, provider-specific tool-calling requirements, rate limits, and overloaded free-tier services. I moved to an OpenAI-compatible architecture with configurable providers, retries, timeouts, and template-based fallbacks.
  • Safe AI Autonomy: The biggest challenge was defining what the agent should and should not do independently. This led to implementing approval queues, execution limits, cooldowns, payment-promise holds, and comprehensive audit logging.

Accomplishments I'm Proud Of

  • Built an AI agent that automates invoice management and payment follow-ups while maintaining human control over financial actions.
  • Developed a Promise-to-Pay Tracker that converts unstructured client messages into actionable payment commitments.
  • Implemented server-side guardrails that remain effective even when external AI agents connect through MCP.
  • Integrated multilingual interactions through English, Hindi, and Hinglish support.
  • Combined invoice generation, payment tracking, automated reminders, financial insights, WhatsApp sharing, and QR-based payments into one platform.

What I Learned

  • Reliable AI agents require strong backend engineering, including input validation, idempotency, execution locks, and meaningful error handling.
  • AI-generated identifiers and numerical values should never be trusted blindly. They must be resolved and validated in backend code.
  • Critical security restrictions should be implemented at the server level rather than relying on prompt instructions.
  • Human approval is essential when AI systems interact with financial workflows.
  • Monitoring tools, webhook inspectors, health checks, and automated fallback mechanisms are crucial for building reliable AI applications.

What's Next for Invoice Copilot

  • Persistent Database: Integrate a database to preserve payment promises, user preferences, invoice history, and Autopilot settings across server restarts.
  • Automated Client Communication: Integrate email and WhatsApp APIs to capture actual client replies instead of requiring manual message input.
  • Client Risk Analysis: Introduce per-client payment reliability scores based on historical payment behavior.
  • Cash-Flow Forecasting: Predict expected payments and future cash flow using historical invoice and transaction data.
  • Recurring Invoices: Support automated invoice generation for retainer-based clients.
  • Multi-Currency Expansion: Improve support for freelancers working with clients across different countries and currencies.

Built With

Backend: Python, FastAPI, Pydantic, httpx

AI & LLM: Groq, gpt-oss-120b, Tool Calling

Payments: PayPal Sandbox, Invoicing API, OAuth, Transaction Search, Disputes, Webhooks

Agent Integration: Model Context Protocol (MCP), Official MCP Python SDK

Frontend: HTML, CSS, JavaScript, Web Speech API

Deployment & Tools: Render, GitHub, ngrok

Important Note

Invoice Copilot currently operates entirely on the PayPal Sandbox, so no real financial transactions or actual money transfers take place.

Application state, including chat history, payment promises, and Autopilot settings, is currently maintained in memory and resets whenever the server restarts. Since the application is hosted on Render's free tier, the service may take approximately a minute to wake up after periods of inactivity.

Built With

Share this project:

Updates

Submission history