forestall

An AI agent that spots PayPal orders heading for an "item not received" dispute and fixes them through PayPal before the buyer files.

Comment

Forestall – AI-Powered PayPal Dispute Prevention

Inspiration

Small online sellers lose "Item Not Received" (INR) disputes they could have won. The parcel was shipped, but tracking information was never attached to the PayPal transaction. Sometimes a shipment stalls without anyone noticing. In other cases, a worried buyer asks, "Where's my order?" but receives no response until the situation escalates into a dispute.

Each lost dispute can cost the seller the refund, the item, transaction fees, and potentially their account standing.

Most chargeback and dispute management tools step in after a dispute has already been opened. I wanted to build something that works before a dispute happens, when the problem is still inexpensive to resolve.

What It Does

Forestall is an AI-powered agent that monitors a seller's PayPal orders from the moment payment is captured.

  • Continuous investigation: During every check, the agent uses tools to investigate live carrier tracking, carrier facility alerts, PayPal order details (including shipping addresses and attached tracking numbers), buyer messages, and the seller's refund and shipping policies.
  • Intelligent risk detection: It explains risks in plain language, such as: "There have been no tracking scans since Memphis, the facility has reported a backlog, and the expected delivery date has passed."
  • Actionable recommendations: For each flagged order, Forestall recommends one appropriate fix: attach missing tracking information, message the buyer, or issue a small partial refund.
  • Safe automation: Actions that do not move money, such as attaching missing tracking information, can run automatically. Refunds and replacements require seller approval with a single tap. Sellers can also use Approve All to clear the entire approval queue.
  • PayPal execution: The backend executes approved actions through PayPal and displays the actual API response.
  • Dispute evidence preparation: If a dispute is opened, Forestall generates an evidence draft using the order's complete timeline. The seller can then submit the evidence through the PayPal Disputes API.
  • Verified protection: An order is marked Protected only after it has been delivered, remained dispute-free for 24 hours, and its tracking information has been successfully read back from PayPal.

How I Built It

PayPal Integration

I integrated the PayPal Sandbox APIs:

  • Orders v2: Checkout, payment capture, order retrieval, and adding tracking information.
  • Payments v2: Refund processing.
  • Disputes v1: Dispute retrieval and evidence submission.
  • Webhooks: Signature-verified handling of PAYMENT.CAPTURE.COMPLETED and CUSTOMER.DISPUTE.CREATED events.

AI Agent

The AI runs on gpt-oss-120b through Groq, with Cerebras running the same model as a backup and smaller models serving as a last resort.

During every check, the model investigates the available evidence and returns its reasoning, risk level, source-tagged facts (carrier, PayPal, or buyer), recommended next check time, and whether the order is safe to close.

The AI never calls PayPal directly. It only investigates and proposes actions. The backend retrieves all PayPal parameters from actual order data and enforces deterministic safety rules:

  • Tracking can only be attached using the order's own tracking number.
  • Refunds are capped at 25% of the order value.
  • Orders are checked at intervals no longer than 24 hours.
  • Missing tracking information is always prioritized and fixed first.

Carrier Tracking

I integrated EasyPost in test mode, including real test trackers and signed webhooks.

I also built a delivery simulator to demonstrate scenarios that the sandbox cannot easily reproduce, including carrier hub backlogs and misdeliveries occurring 380 metres from the PayPal shipping address.

Store Connection

WooCommerce webhooks automatically notify Forestall when orders are shipped, attach tracking information to PayPal, and initiate order monitoring.

Buyers receive email notifications through SMTP and can access a private tracking page where they can also reply to messages.

Technology Stack

  • Backend: FastAPI (Python)
  • Frontend: React + Vite
  • Data Grid: AG Grid
  • Database: Neon Postgres
  • AI: GPT-OSS-120B via Groq and Cerebras
  • Payments: PayPal APIs
  • Shipping: EasyPost
  • Deployment: Vercel

Challenges I Ran Into

1. Keeping the AI Honest

Early versions sometimes generated buyer messages promising things that the seller's policies did not allow.

I solved this by moving policy enforcement into deterministic backend code. The AI can only recommend actions and messages supported by the available facts and the seller's actual policies.

2. Free-Tier AI Rate Limits

When several judges tested the demo simultaneously, AI provider rate limits became a problem.

I implemented automatic failover to a second provider running the same model and configured the system to skip providers that had exhausted their quotas.

Testing showed that smaller models were less reliable when interpreting evidence, so they are only used as a last resort.

Four people running different demo scenarios simultaneously were able to complete their checks successfully.

3. Model Quirks

GPT-OSS occasionally returned tool calls in unexpected formats. Additionally, one of the models I initially used was retired during development.

I updated the agent to handle different tool-call structures and model availability more reliably.

4. PayPal Processing Delays

Attaching tracking information immediately after a new payment capture sometimes failed because PayPal had not finished processing the order.

I implemented automatic retries to handle these timing issues.

5. Realistic Carrier Data

EasyPost test trackers contain fixed historical timestamps, which made it difficult to demonstrate realistic order timelines.

I addressed this by shifting test tracking events to begin shortly after payment capture.

What I Learned

  • Evidence matters: PayPal evaluates INR disputes based on shipping and delivery evidence. Tracking information should be attached to the transaction, and delivery should be verifiable against the buyer's shipping address. Missing or late evidence can make otherwise preventable disputes much harder to defend.
  • AI should decide, deterministic code should act: The most reliable architecture is one where AI investigates evidence and recommends actions, while deterministic backend code controls credentials, validates parameters, enforces financial limits, and executes the final API calls.
  • Automation needs accountability: Not every action should happen without human approval. Separating safe automated actions from financial decisions makes the system more trustworthy.

What's Next

The current demo operates on the PayPal Sandbox, using simulated carrier scenarios and a single seller account.

My next steps are:

  1. Enable live carrier tracking through EasyPost.
  2. Expand support to multiple stores and sellers.
  3. Test the platform with real online sellers.
  4. Measure actual dispute reduction and recovery rates.

Every risk flag, seller approval, automated action, and PayPal API response is already recorded, providing the foundation for measuring Forestall's effectiveness over time.

Built With

Share this project:

Updates

Submission history