Inspiration

Shopping agents usually stop at "add to cart". The hard part of buying online starts after you pay: where is my order, one item arrived broken, the other never came. That is also where people trust automation the least, because money moves back and forth. We wanted one agent that covers the whole loop, from search to refund, while the human stays in charge of every dollar. It is built for busy online shoppers who want help with the whole purchase but do not trust a bot to move their money.

What it does

You type what you need and your budget, for example "two camping chairs for a festival, under $300 total".

  1. Find. The agent searches real products through Channel3, compares a few options in a table, and explains its pick.
  2. Cart and pay. It builds a cart inside your budget cap. Prices come from Channel3 data on the server, never from the model. You review a summary and approve the payment on PayPal.
  3. Track. Ask "Where are my chairs?" and it reads the order and the shipment tracking from PayPal.
  4. Fix. Say "one chair arrived with a broken leg, refund that one" and it prepares a partial refund for exactly one chair. Say "the other never arrived" and it drafts a buyer claim and follows the dispute.

The right side of the screen shows the purchase as four steps, plus three numbers: your cap, what you have paid, and what is waiting for your approval. Refunds and claim settlements appear there as approval cards. Nothing is refunded or settled until you click Approve.

How we built it

  • Agent: Claude (claude-sonnet-5-5) in a tool loop with the Anthropic SDK.
  • PayPal: the PayPal Agent Toolkit (@paypal/agent-toolkit) on the Sandbox. We load its tool schemas with getTools() and pass them to Claude, so the model sees PayPal's own tool descriptions. Calls run through the toolkit's handleToolCall: create_order, pay_order, get_order, create_shipment_tracking, get_shipment_tracking, create_refund, get_refund, list_disputes, get_dispute, accept_dispute_claim.
  • Products: Channel3 search and product detail APIs.
  • App: React + Vite front end, Express API, zod validation on every HTTP input. Tool inputs from the model are checked against the tool JSON schemas and server-side rules.
  • Human-in-the-loop by design: the model is never given create_order, pay_order or create_shipment_tracking. Refunds and dispute settlements are created as approval cards and run only after the shopper clicks Approve.

Guardrails we enforce in code, not in the prompt

  • Budget cap for the whole session (net paid plus the current cart). The agent can set or lower it, never raise it, and never below what is already spent.
  • A payment is captured only for the order behind the current cart, and only if it is still inside the cap. Paying twice, paying after cancel, or approving an old PayPal tab after the cart changed is refused.
  • Money already promised is reserved: pending refund cards and open claims count against what can still be refunded, so the same chair cannot be refunded and claimed twice.
  • Approval cards that can no longer succeed expire automatically. Fully refunded orders show as refunded and cannot be shipped.
  • Sessions are isolated, and the public demo has a per-IP rate limit.

Challenges we ran into

  • Disputes have no buyer API. A buyer opens a claim in the PayPal Resolution Center. In Sandbox the agent drafts the claim text, then tracks it with list_disputes and get_dispute, and settlement goes through accept_dispute_claim after approval.
  • Race conditions around money. We had independent test agents attack the API with parallel checkouts, cancel-then-approve, budget changes mid-payment and refund/claim overlaps. Each bug they found became a server-side rule, and the same scenarios now run as regression checks.
  • Keeping the model away from numbers. Totals, refundable amounts and budget math are computed on the server. The model only chooses products and words.

Accomplishments that we're proud of

  • One conversation covers search, payment, tracking and partial refunds on real PayPal Sandbox calls, then drafts the claim and follows it with the dispute tools.
  • Every money move in the UI says who approved it, and the activity log shows every tool call with its source: Channel3, PayPal Agent Toolkit, app, or you.

What we learned

Agentic commerce is mostly about trust. The model is good at understanding "refund the broken one", but the system has to decide which order, how much, and whether that money is still available. Putting those rules in code made the agent safer and the demo simpler to explain.

What's next

  • Real merchant checkout through Channel3 partners instead of a demo seller.
  • Price watching: wait for a price drop under your cap, then ask you to approve.
  • Saved approval rules, for example "refunds under $20 can run without asking".

Built With

Share this project:

Updates

Submission history