Inspiration
Disputes are where small online sellers lose the most money and time. An "item not received" claim that goes unanswered, or is answered badly, refunds the full amount. Sellers have to gather tracking, weigh fighting against refunding and respond before a deadline, usually alone. We wanted an agent that does the investigation and paperwork while the seller keeps control of the money.
What it does
- Turns every PayPal order into a case with a live timeline built from PayPal data: payment, PayPal fee, refunds, dispute, buyer and seller messages, offers and outcome.
- Dashboard (AG Grid): open disputes, money at risk, cases needing attention, and money kept by settling instead of refunding in full. Search, sort and filter.
- Resolution agent (Claude): for an open dispute, the agent reads the case, the seller's notes (shipping, tracking) and the seller's rules. It dry-runs possible actions against the rules, then recommends one: fight with evidence, settle with a partial refund, refund, message the buyer or wait. Each recommendation comes with reasoning, the facts it used and the money impact.
- Executes through PayPal: offers, claim acceptance, evidence and messages go through the PayPal Disputes API. Actions within the seller's limits run automatically; everything else waits for an Approve click.
- Rules the AI can't override: amount limits, approval and block thresholds as a share of the order, approval before fighting or messaging. Enforced in code. Hard limits apply whatever the settings: no refund above what's left on the payment, only actions PayPal currently allows, strictly valid amounts. Every attempt is logged.
- Catches missed money: for example, payments a buyer approved that were never captured.
How we built it
- PayPal (sandbox): Orders v2 (create, capture), Payments v2 (captures, refunds), Customer Disputes v1 (find disputes, read allowed actions, make offer, accept claim, provide evidence, send message).
- AI: Claude Opus 5.5 via the Anthropic TypeScript SDK's tool runner. The agent has five tools: get_case, get_seller_notes, get_rules, check_action (a dry run against the rules) and submit_recommendation. It uses adaptive thinking and server-side refusal fallback. Buyer-written text is passed to it wrapped as untrusted input.
- App: Next.js 15, TypeScript, Tailwind, AG Grid Community for the case table.
- Safety by design: the AI only proposes. A single gate (
executeAction) re-reads live PayPal state, applies the rules, and is the only path to a PayPal action. 12 automated tests try to talk it past its limits (fake "seller pre-approved" notes, malformed amounts, actions PayPal doesn't allow). - Testing tool: PayPal's sandbox has no buyer-side API, so we wrote a headless buyer simulator (Playwright) that pays, files disputes and accepts offers on the sandbox website.
npm run seedcreates five realistic cases including a real open dispute. - Demo video: narrated with the open-source Kokoro text-to-speech model.
Challenges we ran into
- New sandbox disputes spend several minutes in PayPal review before a seller can respond, and dispute search lags behind new disputes, so the app remembers dispute IDs once known.
- During a dispute PayPal shows a pending "refund" that is really a hold; we label it as a hold so sellers aren't alarmed.
- No buyer-side REST API for disputes, which led to the buyer simulator.
- We documented everything in
docs/sandbox-findings.md.
Accomplishments we're proud of
- In the demo dispute, the agent advised against refunding $120.93: it messaged the buyer with tracking and the customs delay instead, and flagged dates in the records that didn't add up.
- The full loop works in the PayPal sandbox: buyer pays → buyer disputes → seller sends a partial-refund offer through the API → buyer accepts → PayPal partially refunds. Verified end to end with
npm run smoke:dispute. - An agent that is genuinely useful but can't spend the seller's money on its own.
What we learned
Agentic commerce needs a hard boundary between what the AI decides and what the payment system executes. Putting that boundary in code, with the AI able to dry-run actions against it, made the agent both more useful and trustworthy.
What's next
Webhooks for real-time dispute alerts, evidence file uploads (tracking screenshots), carrier tracking lookups, and a shareable seller track record built from resolved cases.
Built With
- ag-grid
- claude
- nextjs
- node.js
- paypal
- playwright
- tailwindcss
- typescript