Inspiration
For a one-person online shop, a PayPal dispute is a small legal case with a deadline. The owner has to read the claim, dig up tracking, guess whether seller protection applies, and write a statement in the right format before the window closes. Many owners refund everything to make it go away, losing money on claims they would have won. Others miss the deadline and lose by default. We wanted to give a small shop the judgement of a dispute specialist in one click.
What it does
- Pulls every open dispute from PayPal through the Disputes API, with transactions, items, the message thread and buyer attachments, and shows them in an AG Grid queue sorted by deadline.
- Fills in the shop's records automatically from the tracking the shop already added in PayPal (Tracking API). The owner can add anything else, such as listing details or customer history.
- Reviews each dispute with an LLM and returns a structured decision: contest with evidence, offer a partial refund, refund in full, or ask the buyer for details, with estimated odds, risk, an evidence checklist and fraud signals.
- Drafts the exact response: the statement to PayPal (with carrier and tracking for proof of fulfillment) and a message to the buyer.
- Sends it back to PayPal only after the owner approves: provide-evidence, make-offer, accept-claim or send-message. Every send goes into an audit trail.
It is honest about weak cases. With no proof of delivery, it says the claim will likely be lost and lists what is missing. When the shop's own records show the shop is at fault, it recommends refunding.
How we built it
- Backend: Node.js and Express. A small PayPal client handles OAuth client credentials with token caching, the Disputes API (including multipart evidence uploads) and the Tracking API. Buyer attachments are fetched server-side with the OAuth token, only for files that belong to the dispute and only from the PayPal API host.
- AI: OpenRouter, with forced tool calling against a strict JSON schema. The prompt includes the dispute, the message thread, attachment names, the shop's records and its policy, and tells the model never to invent facts. Output is repaired and validated on the server (offers capped at the disputed amount, unknown actions rejected). If the model is slow, rate limited or returns something unusable, it retries once, then a built-in rules engine takes over so the app never breaks. An hourly cap protects the API budget on the public demo.
- Frontend: vanilla JavaScript with AG Grid Community for the queue, and a case panel that puts the recommendation and editable drafts first.
- Hosting: Render, deployed from a
render.yamlBlueprint. - Safety: the server refuses to run against live PayPal. Nothing is sent without a click on Approve.
- Tests: 49 Vitest tests cover the PayPal client, the AI engine and its fallbacks, and the API flows.
Challenges we ran into
- Free models are inconsistent. The router picks a different model per request, and some ignore the tool or answer in plain text. We added a JSON fallback, output repair, one retry, a timeout, and the rules engine as a safety net. The page always says which model wrote a draft, or why the rules engine did.
- Slow models hit the host's request limit. Reviewing six disputes in one request was cut off, so the app now reviews them one at a time and updates the queue as each finishes.
- Empty sandboxes and shared demos. A new sandbox account has no disputes, and a public demo is shared by every visitor. We added a sample shop that each visitor gets their own copy of, opened with saved AI reviews so nobody waits on the free-model quota, and made the real sandbox review-only on the public site.
Accomplishments that we're proud of
- An end-to-end loop on real PayPal data: a sandbox dispute pulled in, reviewed, and an approved reply delivered to the buyer inside PayPal.
- Recommendations that refuse to overclaim: they lower the odds and list missing evidence instead of inventing it.
What we learned
The value is not in the model writing text, it is in the guardrails around it: the schema, the validation, the fallbacks, and keeping a human on the final click.
What's next for Dispute Copilot
- Pull order and listing data from store platforms (Shopify, WooCommerce) so records fill in automatically.
- Persist records and reviews in a database (today they live in memory and reset on restart).
- Let the model read buyer photos with a vision model.
- Notify the owner when a new dispute arrives or a deadline is close.
Built With
- ag-grid
- express.js
- javascript
- llm
- node.js
- openrouter
- paypal
- paypal-disputes-api
- render
- vitest