Inspiration

Small merchants live inside PayPal, but they can't see why their money moves. Refunds creep up, a dispute deadline passes unnoticed, a wholesale customer stays 34 days late on an invoice. The data is already in PayPal; turning it into a decision takes an analyst that a coffee roaster, a café or a course creator doesn't have.

We also wanted to answer the hard question of agentic commerce: an AI that can move money is only useful if the owner can trust it. So we built an agent that does the analyst's and the clerk's work, while the owner keeps the final click.

What it does

MerchantPilot connects to a PayPal business account and works in three steps: Ask → See → Approve.

  • Ask: "Why are my refunds up?" The agent reads transactions, disputes, invoices and subscriptions through PayPal's APIs and runs deterministic analytics. In the demo store it finds that ~40% of one product's orders were refunded in 10 days, versus under 2% before. That points to a damaged batch.
  • See: it works with AG Studio's built-in agents to add the chart that proves the finding to a live five-page report (Overview, Sales, Disputes, Collections, Subscriptions). Click any invoice, customer or dispute for its full story.
  • Approve: it prepares the fixes (refunds, invoice reminders, PayPal payment plans, dispute evidence packs) as cards in the chat. The owner clicks Approve and the action executes on PayPal through the PayPal Agent Toolkit.

Governance is built in: approval rules (auto-approve small amounts, two approvers above a threshold, a daily money-out cap) and a persistent audit trail.

It also tracks recurring revenue from PayPal Subscriptions (MRR, churn, revenue at risk from failed renewals) and forecasts cash flow with what-if scenarios. For several businesses there is a 0–100 portfolio health score with an owner briefing. Signed PayPal webhooks become real-time alerts, and it works by voice in English and Spanish. Results go out as PDF, Excel, a Power BI feed, QuickBooks/Xero exports or an MCP server that other AI agents can use. A 3-minute guided tour shows a first-time visitor everything.

In the demo store, the first minute surfaces about 5,750 USD of money at stake and ~310 USD/month of recurring revenue at risk, each with a ready-to-approve action.

How we built it

  • Next.js 16, React 19 and TypeScript on Render, with Postgres for the audit trail, rules and businesses.
  • PayPal: Transaction Search, Disputes, Invoicing (with line items) and Subscriptions APIs, plus signature-verified webhooks.
    • Refunds, dispute acceptance and invoice reminders execute through @paypal/agent-toolkit with a least-privilege tool set.
    • Dispute evidence uploads and partial-payment plans use the REST API behind the same approval gate.
  • AG Studio 3 Agent Framework: our custom agent delegates chart building to Studio's built-in agents.
    • A custom LLM adapter keeps every API key on the server.
    • Three custom widgets: Money at stake, Recurring revenue, and a Cash-flow forecast built with AG Charts.
    • A five-page report, drill-down grid cells, in-chat approval cards and a PayPal-blue theme.
  • AI: Anthropic Claude through the Vercel AI SDK, with typed tool calling. The model never does arithmetic: every number comes from deterministic code. Proposals are validated against real data before they are queued.
  • MCP: a server with 18 tools. Proposals made through it return signed approval links.
  • Quality:
    • 67 unit tests (Vitest)
    • 7 browser end-to-end suites (Playwright) covering agent → tool → approval → execution
    • a sandbox seeder that recreates every demo scenario on a real PayPal sandbox account
  • AI tools in development: Claude as a coding assistant, plus the PayPal AI-Toolkit for sandbox work.

Challenges we ran into

  • Making an agent safe enough to touch money. We separated propose from execute. Validation runs both at proposal time and at approval time, approval links are signed and single-use, and added PayPal secrets are encrypted at rest.
  • Subscriptions have no "list all" API. We discover subscription IDs from BILLING.SUBSCRIPTION.* webhooks and from recurring payments in Transaction Search.
  • Two agents, one chat. We coordinated our agent with AG Studio's agents so that charts land on the right page instead of being duplicated.
  • A demo judges can trust. We built deterministic demo stories (a damaged batch, carrier disputes, late wholesale customers, subscription churn) next to the live PayPal sandbox account, and added a guided tour so anyone knows what to try.

Accomplishments that we're proud of

  • A real human-in-the-loop agent: it explains, proves, proposes and then executes on PayPal after one click, inside rules the owner controls, with a full audit trail.
  • Deep use of AG Studio: our own agent cooperates with Studio's agents, alongside custom widgets, drill-downs and in-chat cards.
  • One engine, many surfaces: the same analytics and approvals power the dashboard, voice, email, Power BI and other AI agents via MCP.

What we learned

  • Agentic commerce needs governance more than autonomy. Rules, two-person approval and audit trails are what make an owner comfortable letting AI act.
  • LLMs are great at explaining numbers and poor at computing them. Keeping the math deterministic made the answers trustworthy and testable.
  • PayPal's sandbox, webhooks and Agent Toolkit are enough to build a product that feels real end to end.

What's next for MerchanPilot

  • Sign-in with PayPal and per-user roles, so approvals come from verified identities.
  • Production PayPal accounts after a security review.
  • More Agent Toolkit actions as they become available, and agent-to-agent flows: supplier or carrier agents negotiating refunds and disputes over MCP.
  • Pilots with real small merchants to measure the time saved and the money recovered.

Built With

  • ag-charts
  • ag-grid
  • ag-studio
  • anthropic-claude
  • exceljs
  • mcp
  • next.js
  • node.js
  • openai
  • paypal
  • paypal-agent-toolkit
  • paypal-rest-api
  • paypal-subscriptions
  • paypal-webhooks
  • playwright
  • postgresql
  • react
  • render
  • tailwindcss
  • typescript
  • vercel-ai-sdk
  • vitest
Share this project:

Updates

Submission history