-
-
Dispute Desk: plan the whole PayPal dispute queue, not one case.
-
Planner: 1.30% counted, 1.82% if open inquiries escalate, per-case plan lines.
-
Studio chat delegates to dispute-analyst; acceptance comparison with chart and grid.
-
Approval card bound to the SHA-256 of the exact request; nothing is sent until approved.
-
Case resolved (SELLER_ISSUED_REFUND) and kept out of the dispute rate.
Inspiration
What it does
How I built it
Challenges I ran into
Accomplishments that I'm proud of
What I learned
What's next for Dispute Desk
Inspiration
The first user is the owner of a small US online store who answers PayPal disputes alone and sits at a 1.3% dispute rate. PayPal's Resolution Center shows the current rate and fee tier, but not where the rate goes if today's open inquiries escalate, or which ones to settle to stay under the 1.5% High Volume line. Above that line PayPal's help pages say the Dispute Fee rises from 15.00 to 30.00 USD, the seller may have to reply in 3 days instead of 10, and Seller Protection can be lost. An inquiry settled with the buyer before it becomes a claim is not counted in the rate and carries no dispute fee.
The result that surprises: in the app's demo scenario, a $20 offer on a $66.12 case looks $31.78 cheaper per case, but refunding it is $43.22 cheaper for the account ($84.52 against $127.74 expected cost over the queue), because a declined offer escalates and pushes the store to 1.75%, over the line, while the refund plan stays at 1.47%. These are the app's own demo numbers.
What it does
- Projects the rate before it moves. The demo store is at 1.30% counted so far and reaches 1.82% if its three open inquiries all become claims. For each open case it shows when an escalated claim would enter and leave the 3-month window.
- Plans the whole queue, not one case. It compares per-case, refund-first and fight-everything plans by expected cost under assumptions the seller sets (buyer acceptance, win rate). The offer wins above about 74% acceptance, and the screen shows that boundary. These assumptions are the seller's, not statistics.
- Applies PayPal's published fee and Seller Protection rules in code. The model never computes money.
- Drafts, then waits. Claude drafts the reply from the dispute, order and tracking records; a draft containing a dollar amount the server did not compute is rejected. Every PayPal write is an approval card bound to the SHA-256 of the exact request body, so editing one word voids the approval. Before sending, the server re-reads the dispute and only calls an action PayPal currently lists in the dispute's links.
- Runs inside AG Studio. The product is an AG Studio dashboard with four custom widgets (Dispute Rate Planner, Decision Card, Deadline Runway, Saved vs Advised), a theme and two saved layouts. The Studio chat's lead agent delegates what-if questions to our
dispute-analystagent, which picks server calculators and puts the result on the dashboard.
How we built it
React 19 and Vite on the front end with ag-studio and ag-studio-react 3.1.0; Node.js and Express on the back end. AG Studio ships no model connection, so we wrote a Claude adapter (AgLlmAdapter) that streams the Anthropic Messages API as AG-UI events, put Studio's five built-in agents on it, and added the custom dispute-analyst agent. PayPal side: the Disputes API (accept-claim, send message, offer, escalate, evidence), PayPal Agent Toolkit (list_transactions, dispute reads, accept_dispute_claim), and the Orders and shipment tracking APIs. All rules live in server/domain and are covered by an offline test suite that reproduces every demo number.
How PayPal and AI run on the hosted demo: Claude Sonnet (claude-sonnet-5-5) answers live through the Anthropic API, with per-IP-hour and per-day caps. When the API fails or a cap is hit, the action still finishes with a labelled recorded Claude run or a rule-based stand-in, and the screen says which. PayPal runs in sandbox demo mode: case A is a real PayPal sandbox dispute, and approving its refund calls api-m.sandbox.paypal.com; cases B and C run on an offline stand-in whose response shapes follow real sandbox responses we recorded on 2026-11-11. The header chip and banner always show the active mode. The demo video was recorded on the hosted app with live Claude.
The project was built for this hackathon within the Oct 1 - Nov 12 2026 submission period (the sandbox runs and recordings in VERIFY.md are dated 2026-11-11 and 2026-11-12).
Challenges we ran into
- Sandbox disputes cannot be created by API with our app's scopes, so we automated the buyer side of the sandbox Resolution Center (about 2 minutes per case, sequential).
- Each seller action puts a dispute under review and a second action in that window returns 422; the app re-reads the dispute and only enables what PayPal's links allow.
- A full sandbox fight path takes about 20 minutes (the adjudicate link appears about 12 minutes after evidence), so the app plays a recorded run for it and labels it a sandbox simulation.
- In Agent Toolkit 1.11.0 the
accept_dispute_claimschema validatesnotewith an ID pattern, so a sentence is rejected; the app sends the same JSON through REST. - PayPal does not say whether the current month counts in the "previous 3 calendar months"; the planner shows its window assumption and lets you switch it.
- Studio's chat history keeps only the tool calls Studio ran itself, so our analyst repeated calculations; the server now keeps each analyst run's own history between round trips.
Accomplishments that we're proud of
- The counter-intuitive result (a cheaper-looking offer loses at the account level) comes straight from PayPal's published rules and is reproducible with the numbers on screen.
- Real sandbox disputes went from approval in the app to RESOLVED (
SELLER_ISSUED_REFUND) in about 1m40s at the inquiry stage and 1m45s at the claim stage (VERIFY R15, R19), and the walkthrough refund ran on a real sandbox case in about 2m13s (R24). - Seller writes through the approval cards (message, $20 offer, escalate then evidence with tracking) worked on the sandbox (R23).
- A 30-case AI evaluation run once through a local Claude Sonnet account: checklist accuracy 100%, source id validity 100%, 0 invented dollar amounts, 100% adversarial refusals, 1 draft flagged (EVALS.md). It was not run on the hosted API path.
- Judges always have a working path with no keys and no login, and the AI part stays checkable because money lives in code.
What we learned
- For a PayPal seller, the cheapest answer to one dispute is not always the cheapest for the account.
- Sandbox dispute timing and HATEOAS links decide what an app can do next, so the app must read them every time.
- Keeping money in code and letting the model only choose tools and draft text makes the AI part checkable.
What's next for Dispute Desk
- Learn the acceptance and win assumptions from the seller's own outcomes.
- Returns flow (acknowledge-return-item) for not-as-described claims.
- Marketplace mode: one row per seller in an AG Grid with the planner as the drill-down (needs PayPal partner access; not built).
- Dispute write tools (message, evidence, offer, escalate) for the Agent Toolkit.
Honest notes: store figures (3-month sales, sale count, past claims) are a demo store ledger because a sandbox seller has no such history; the dispute rate shown is our recalculation from PayPal's published formula, not PayPal's official number; the webhook is implemented but was not run against the sandbox (VERIFY R7).
Built With
- ag-grid
- ag-studio
- agentic-commerce
- ai-agents
- anthropic
- claude
- disputes
- ecommerce
- express.js
- fintech
- human-in-the-loop
- node.js
- paypal
- paypal-disputes
- react
- seller-tools
- vite