-
-
The dashboard: what's owed, what's late, and the six-stage resolution loop where every open invoice has exactly one place.
-
One agent run, every step visible: sync, rank by risk, diagnose, check the rules, act or ask.
-
Why it's stuck: client words separated from inference; a specific fix (add PO-88412), shown in rules-only mode.
-
Policy checks pass, the owner approves, and the result says plainly: "simulation: PayPal was not called".
-
The client's private page: only plans inside the owner's rules, here 3 × $400 with a simulated first payment.
-
Follow-through: Bluebird moves to Agreed with $400 collected (simulated) and $800 still owed.
-
Insights in AG Studio: a receivables report over read-only tables with a self-serve report builder.
-
Our Unstuck Insights agent, built on the AG Studio Agent Framework, answers from the data and opens the matching report.
The problem
Imagine a two-person design studio sends a PayPal invoice, does the work, and waits. More than half of US small businesses have unpaid invoices outstanding, and those that do are owed $17,500 on average (QuickBooks, 2025). About three in ten owners have delayed their own pay because clients paid late (Bluevine, 2026).
Sources: QuickBooks Small Business Late Payments Report · Bluevine Small Business Survey
Invoicing tools are good at telling you which invoices are overdue. They're silent on why. And the reason is different every time: an accounts-payable team that can't pay without a PO number, a client who is short on cash this month, a dispute about the work, an invoice sent to someone who left, a cheque in the post, a promise to pay "by Friday" that quietly passed. The usual response, another reminder, fixes exactly one of those causes, and repeated chasing strains the relationship, so many owners stop chasing at all.
Our insight
Getting unstuck isn't a reporting problem. It's a decision-and-action problem. Each cause has a specific remedy, and most of those remedies are things PayPal Invoicing can already do: put the PO on the invoice and re-send it, switch on partial payments for a plan, pause automatic reminders during a dispute, record a payment that arrived another way. What's missing is something that works out the cause, picks the matching remedy, keeps the owner in control, and follows the invoice until it's paid.
What we built
Unstuck is an AI receivables-resolution agent for businesses that bill through PayPal Invoicing. For every unpaid invoice it:
- understands why it's stuck. A Google Gemini diagnosis keeps what the client actually said (quoted) apart from what it infers, recommends a next step, and says so when the cause is unknown;
- resolves it with a cause-specific PayPal Invoicing action: a reference/PO update and re-send, a partial-payment plan, a reminder to the right person, paused reminders, a recorded payment, or an early-payment discount that expires on its own;
- keeps the owner in control. A deterministic policy engine decides whether each action runs on its own, waits for approval, or is blocked. Anything that changes money waits for the owner;
- brings the client in. Every reminder links to a private page where the client can explain, promise a date, or pick a payment plan, but only plans the owner's rules allow;
- follows through. Payments are read back from PayPal; installments advance the minimum due; a missed promise sends the invoice back to the agent.
The dashboard shows this as a resolution loop: every open invoice sits in exactly one stage (Spotted → Understood → Waiting for you → Acted → Agreed → Paid), computed from recorded facts.
How it works
- Sync. OAuth into the PayPal sandbox and pull invoices through the Invoicing v2 API. PayPal stays the source of truth.
- Rank. A transparent risk score (named factors, not a black box) decides what the agent looks at first.
- Diagnose. Gemini receives the invoice facts, payment and reminder history, and the client's messages (wrapped as untrusted data), and returns a schema-constrained diagnosis.
- Turn it into an action, in code. Unstuck re-validates the answer and builds the PayPal action itself. Plan maths, discount caps, PO formats and links never come from the model.
- Check the rules. The policy engine returns auto, needs approval or blocked, with every check shown on the action card.
- Act and verify. Before executing, Unstuck re-reads the invoice from PayPal and re-runs the rules, so a stale approval can't fire. After a PayPal update, it reads the invoice back and reports "confirmed" only if the change is there; otherwise it says the request was accepted.
- Follow up. Installments due, missed promises and client replies come back into the next agent run.
What makes it agentic is that it works the whole loop on its own, but only inside boundaries the owner set and can see.
Engineering and architecture
- Next.js 16 + React 19 + TypeScript, with SQLite for local state; PayPal remains the system of record.
- PayPal Developer Platform (sandbox): OAuth 2.0 client credentials; Invoicing v2: list/get,
remind, full-replacementPUT(reference, CC, partial payments, minimum due),conditional-rules,payments,cancel-reminders, create and send; Webhooks: signature verification viaverify-webhook-signature, event deduplication, and a re-read of the invoice (the payload is never trusted). Every write carries aPayPal-Request-Id, so retries are idempotent. Production PayPal is refused by design. - Google Gemini (
gemini-3.5-flash-lite, Google Gen AI SDK) behind a provider-independent interface (an Anthropic Claude adapter is optional), in two roles: the diagnosis, and a client-facing assistant limited to four allowlisted, schema-checked tools. - Reliability. Gemini sometimes returns HTTP 503, and the SDK's own retries ignored our pacing and budget. So every AI call goes through one retry runner: paced and budgeted per attempt, backoff with jitter, clamped
Retry-After/RetryInfo, a daily-quota pause and a circuit breaker with a single recovery probe. If the AI can't answer, the invoice still gets a clearly labelled rules diagnosis, never a fake AI one. - Safety. Agent-proposed money changes always need the owner. Agent-written messages with foreign links, other payment details or legal threats never go out automatically. Per-invoice locks stop overlapping runs from double-sending.
- AG Grid and AG Studio. AG Grid powers the risk-ranked receivables board and the audit log. AG Studio powers Insights, including our own Unstuck Insights agent built on the AG Studio Agent Framework, which answers receivables questions in Studio's AI panel and opens the matching report.
- Tests. 276 automated tests (including a deliberately compromised model that tries to mark invoices paid, grant a 90% discount or inject instructions through a "PO number"), 26 contract checks against a strict mock PayPal, and a browser journey.
Challenges and what we learned
- "Accepted" isn't "done". A 200 from PayPal means PayPal accepted the request, not that the client received or acted on anything. We built the reporting around that: simulated, accepted, confirmed on re-read, and paid are four different words in the UI.
- PayPal's invoice update replaces the whole invoice. We GET, strip read-only fields, change one thing and PUT, and proved it against a strict mock that rejects read-only fields.
- Stale approvals. Our own audit found an approved action could run after the invoice had changed. Execution now re-reads the invoice and re-checks the rules.
- Real AI is unreliable at the edges. 503 bursts, per-minute limits and daily quotas taught us to design for failure first: honest fallbacks, a circuit breaker, and no retry storms.
- Races. Two overlapping diagnoses could both pass the reminder-cadence rule and message a client twice. Per-invoice locks fixed it, with tests that fail without them.
- Sandbox vs simulation. Our cloud build environment couldn't reach the sandbox, so we built a strict mock PayPal and a labelled simulation mode, and kept them visibly separate from the real sandbox. On our own machine we seeded a real sandbox (13 invoices: 8 open, 5 paid) and synced it read-only.
- The real lesson: an AI agent near money needs more engineering around the model than inside it: rules, approvals, idempotency and honest reporting.
Impact and future potential
Unstuck is designed for freelancers and small service businesses on PayPal Invoicing, who can't afford a collections team and don't want to damage client relationships. The intended value is less time spent working out what's wrong, fewer generic reminders, faster resolution of fixable problems (a missing PO, a cash-flow plan), and a clear record of what was tried. This is intended impact, not measured impact: we have no user or outcome data yet, and we don't claim any.
Next: publish the Gemini evaluation (26 scenarios, strict scoring), run the sandbox write path end to end with a registered webhook, add an email inbox so client replies arrive automatically, and expose the policy-gated actions as an MCP server so a client's own AP agent could settle through the same rules.
Where things stand (honestly)
- Real: the PayPal Invoicing integration (exercised against a strict mock in CI, and against the real sandbox for OAuth, sync and seeding on our machine); Gemini diagnosis (verified with real API calls on our machine).
- Simulated in the demo: actions, and the client's payment. Each is labelled "(simulation: PayPal was not called)" in the product itself.
- Not yet verified live: webhooks and sandbox writes made by Unstuck's actions.
What makes Unstuck different
Most tools tell you an invoice is overdue, and most AI tools write a nicer reminder. Unstuck asks why, answers with the client's own words as evidence, applies the PayPal action that fits the cause inside rules you set, involves the client on fair terms, and tells you exactly what happened. Not a tracker, and not a chatbot: a resolution loop built on PayPal Invoicing.
Built from scratch during the hackathon (first commit 4 Nov 2026).
