Inspiration

A small seller with a few hundred PayPal sales a month closes the books in a spreadsheet: export transactions, export orders, VLOOKUP, squint. The mistakes that slip through are the expensive ones. A customer charged twice, a wholesale invoice nobody chased, a refund issued in PayPal that never reached the books, a chargeback that quietly took back a sale plus a fee. Accounting tools match bank deposits, but PayPal payouts arrive lumped together and net of fees, so the real detail only lives inside PayPal. I wanted the close a bookkeeper would do, done in a minute, with the owner still in control.

What it does

Closeout pulls a month from PayPal and checks every transaction against the shop's own order records.

  • Reconciles. A ledger built on AG Grid ticks off every record that ties out and highlights what doesn't. It catches duplicate payments, overdue and partly paid invoices, refunds and sales missing from the books, chargebacks with dispute fees, fees above the seller's schedule, currency conversion shortfalls, and orders PayPal has no payment for.
  • Explains. Gemini writes the month-end summary and, for each exception, a plain-English explanation, a likely cause and a draft note to the customer where one is needed. An AG Charts figure shows where the month's sales went: the bank, still in PayPal, fees, refunds and chargebacks.
  • Fixes, with approval. Every action first shows exactly what will happen, including the PayPal API call and an editable note to the customer: refund a duplicate through the Payments API, send a reminder through the Invoicing API, or record an adjusting entry for the bookkeeper. Nothing moves until the owner approves it.
  • Answers questions. Ask about the month in plain English; answers come only from the month's figures.

It runs on a demo month (a fictional candle shop: 312 transactions in PayPal's own API format, 303 orders, nine planted problems) or live against a PayPal sandbox account.

How I built it

  • Stack: Python and FastAPI, a vanilla JavaScript front end with AG Grid Community and AG Charts Community, and a ledger-pad design: green ticks, highlighter, red ink only where money doesn't tie out.
  • PayPal: OAuth client credentials; Transaction Search for every payment, refund, chargeback, conversion and transfer in the month; Invoicing v2 for invoice status and reminders; Payments v2 for refunds. A sandbox test store uses Orders v2 and the JS SDK to make real checkouts, plus the mistakes real shops make: a double charge, an off-book sale, a refund done only in PayPal.
  • The engine owns the numbers, the AI owns the words. Matching runs in plain, tested code; Gemini 2.5 Flash only explains the results (Claude works as an alternative provider). Before any AI text is shown, Closeout extracts every number in it and checks each one against the facts the model was given. Text with an invented figure is retried once, then replaced with a rule-based explanation.
  • Money safety: refunds carry a deterministic PayPal-Request-Id, and Closeout refuses to move money twice for the same item.
  • 55 automated tests that need no network. I built it with Claude as an AI pair programmer, testing each step against my own PayPal sandbox.

Challenges I ran into

  • Transaction Search lag. PayPal can take up to three hours to report new payments, so fresh sales looked missing. Closeout reads last_refreshed_datetime and shows those sales as waiting for PayPal instead of flagging them.
  • Trusting AI with money. A model that rounds or invents a figure is worse than no model. The numbers guardrail and rule-based fallbacks mean a wrong number never reaches the owner.
  • Model availability. Gemini returned 503s under load, so calls retry, fall back across models and cache answers, and the app keeps working on rules if the AI is down.
  • Realistic sandbox data. A new sandbox account has nothing to reconcile, so I built the test store to create real PayPal checkouts, invoices and mistakes.

Accomplishments that I'm proud of

  • A full close on live sandbox data: a real refund through PayPal's API, a real invoice reminder, and the month tying out afterwards.
  • Every number Gemini shows is checked against the data first.
  • A product that reads like a bookkeeper's ledger, with a self-playing guided tour at /?tour=demo.

What I learned

How PayPal's reporting data fits together: event codes, reference IDs that tie refunds and chargebacks back to the original payment, and separate fee and currency lines. And that AI is most useful here when it explains and drafts while plain code decides.

What's next for Closeout

  • Connect real sellers through PayPal's partner onboarding instead of app credentials
  • Webhooks for a continuous close instead of a month-end one
  • Dispute handling through PayPal's Disputes API
  • Adjusting entries pushed to QuickBooks and Xero, and orders imported from Shopify and WooCommerce instead of CSV

Built With

  • ag-charts
  • ag-grid
  • elevenlabs
  • fastapi
  • fintech
  • gemini
  • javascript
  • paypal
  • paypal-js-sdk
  • paypal-orders
  • paypal-payments
  • paypal-transaction-search
  • playwright
  • pytest
  • python
Share this project:

Updates

Submission history