-
-
Describe the job in plain words: the AI agent drafts a real PayPal invoice, and nothing is sent until you tap Approve & send.
-
Receivables dashboard built with AG Grid: who owes you, what's overdue, and each payment's value in rand at that day's rate.
-
Ready-made AG Studio report: rand received, rand per month and per client. Tap Edit report to reshape it in the browser.
-
Tax-year statement as a PDF or CSV: every payment converted at the rate on the day it was paid, the SARS default method.
-
How Crossbill works: the whole loop on one page
Inspiration
PayPal can't invoice in South African rand, so freelancers here bill their overseas clients in US dollars. That turns every job into three chores: writing the invoice by hand, chasing the client when it's late, and, at tax time, converting every single payment into rand at the right exchange rate. Freelancers like me are part of a large group: the World Bank estimates there are 154 million to 435 million online gig workers worldwide, 4.4% to 12.5% of the global labour force (Working Without Borders, 2023).
That last chore is the one people dread. For South African individuals, foreign income is converted at the spot rate on the day it was received (SARS Interpretation Note 63). Most freelancers rebuild this in a spreadsheet once a year, looking up dozens of old rates.
I'm a freelance web developer in South Africa, and I wanted one place where I could describe the job in plain words, approve it, get paid, and find my tax books already done. That's Crossbill.
What it does
Crossbill is an AI agent that writes your invoices, chases late payers and keeps your tax books. You describe the job, approve the invoice and get paid.
- Plain words to a real PayPal invoice. Type "Invoice Jack Smith for 3 days of Next.js work at USD 250 a day" and Crossbill drafts a PayPal invoice with the right line items and units: hours, counted items such as lessons or words, or a flat fee.
- Nothing is sent without you. The agent only proposes. An invoice reaches PayPal only when you tap Approve & send, and that rule is enforced in code, not just in the prompt.
- Who owes you. Ask "Who owes me and who has paid?" and the agent reads your invoices from PayPal, including how many days each one is overdue.
- Chases late payers. The agent drafts a polite, specific reminder; you approve it and PayPal sends it.
- Books in your currency. Every payment, part-payments included, is converted at the exchange rate for the day it was paid. A verified PayPal webhook records each payment the moment it lands.
- A tax-ready statement. The South African tax year (1 March to end of February), a single month or any date range: monthly totals, every payment with its rate, and PDF and CSV downloads.
- A receivables dashboard. An AG Grid table of every invoice, plus a ready-made AG Studio report (totals, rand per month, rand per client) that any freelancer can reshape in the browser.
- Talks like a helper. Greetings, vague or off-topic messages get a short, polite answer, a follow-up question and example prompts as buttons. Missing invoice details are asked for, never guessed.
- Any freelancer, many currencies. Tutors, translators, designers and developers. Rand by default, plus about 30 other currencies from European Central Bank rates.
How we built it
Crossbill is a Next.js app (App Router, TypeScript, Tailwind CSS) deployed on Vercel. It has no database: the books are rebuilt live from PayPal on every request, so they can never drift out of sync.
- The agent. Built with the Vercel AI SDK. OpenAI's open-weight
gpt-oss-120bruns on Groq as the main model. If it fails or hits its free quota, Groq's smallergpt-oss-20btakes over with its own free quota, and Google Gemini answers if Groq itself is down. - Six tools.
propose_invoice,list_invoices,earnings,income_statement,propose_reminderandshow_examples. The agent can read from PayPal and propose actions, but it has no tool that sends anything. - Approve to send. Sending lives in separate routes that run only when you tap Approve. Each invoice card carries one request id, so a double tap can never create two invoices.
- PayPal Invoicing v2. Next invoice number, create, send, list, read and remind, with your business name as the invoicer.
- Payments in real time. PayPal calls the webhook on
INVOICING.INVOICE.PAID. Crossbill asks PayPal to verify the signature, then re-reads the invoice for the authoritative amount. - The rate on the day you were paid. Each payment date gets its USD rate from Frankfurter (European Central Bank), with a community rates API as fallback; past rates are cached.
- AG Grid and AG Studio. The invoice table is AG Grid Community, themed to match the app. The report is AG Studio over two related data sources, invoices and payments.
- The statement. A server-built A4 PDF (pdf-lib) and a CSV, so it downloads reliably on any device.
- No invented numbers. Every money figure the agent quotes comes from a tool result, already formatted; the model never does currency arithmetic itself.
The full architecture, with 13 diagrams and the code behind each step, is in docs/ARCHITECTURE.md.
Challenges we ran into
- Making approval real, not a promise. A prompt that says "don't send without asking" isn't a guarantee, so I took the ability to send away from the agent entirely.
- Weekends and public holidays. The European Central Bank publishes no rate on those days, so a Saturday payment needs the last working day's rate. Crossbill uses it and shows the rate's own date beside the payment date.
- Part-payments. One invoice can be paid in several parts on different days, so each part gets its own rate.
- Free AI tiers run out. Under load the main model hit its free quota, so I added retries on rate limits and an automatic fallback chain: a smaller Groq model with its own quota, then Gemini.
- Emails PayPal can't check. PayPal has no API to tell whether an email belongs to a PayPal account, and a sandbox invoice to a made-up address sits unpaid forever. Crossbill only sends to a list of sandbox test accounts, checked both when the agent drafts and when you approve.
- Models that type their tools. Sometimes a model writes a tool call as text instead of making it. Crossbill strips that from replies and still shows the right buttons.
Accomplishments that we're proud of
- It works end to end with real PayPal invoices. Describe, approve, send, the client pays, the webhook lands, and the payment shows up in rand at that day's rate. Judges can run the whole loop with the test login.
- Tax-ready by design. The books follow the actual SARS rule for foreign income, record the rate source and date for every payment, and export to PDF and CSV for an accountant.
- Safe by construction. Human approval, verified webhooks, idempotent invoice creation, per-IP rate limits, strict input validation, a sandbox allowlist and security headers (a content security policy, no framing, HTTPS only).
npm auditreports no known vulnerabilities. - Accessible and phone-ready. Every page passes an automated accessibility audit (axe) with no violations: keyboard-first, a skip link, replies announced to screen readers and WCAG AA contrast. It works on a 320-pixel screen, installs as an app and shows a clear offline page.
- Free to run. Every service is on a free tier, and there's no database to pay for or pause.
What we learned
- An agent is only as safe as its tools. Taking a capability away from the model is stronger than asking it not to use it.
- Let the model talk and the code count. Language models are great at turning plain words into structure and unreliable at arithmetic, so every money figure comes from code.
- Tax rules are product requirements. SARS Interpretation Note 63 shaped the data model: one rate per payment date, with its source, rather than one rate per invoice.
- PayPal's invoicing API does more than I expected. Units of measure, payment transactions with dates, reminders and signed webhooks covered almost everything a freelancer's back office needs.
- AG Studio changes who builds reports. Two related data sources let me ship a useful report on day one while letting each freelancer build their own.
What's next for Crossbill
- Live mode for real PayPal accounts, with each freelancer signing in with their own PayPal.
- Local clients too. Rand invoices for clients at home, paid instantly by PayShap or instant EFT and recorded in the same books as overseas income.
- The average-rate method. SARS lets individuals elect the year's average exchange rate instead of the spot rate; Crossbill will offer both.
- Saved clients and default rates, so a repeat invoice is one short sentence.
- Sharing the statement with an accountant through a private link.
Built With
- ag-grid
- ag-studio
- frankfurte
- google-gemini
- gpt-oss
- groq
- next.js
- paypal
- paypal-invoicing-api
- pdf-lib
- react
- tailwindcss
- typescript
- vercel
- vercel-ai-sdk
- zod
