Inspiration

California's click-to-cancel rule (Cal. Bus. & Prof. Code section 17602(e)(2), for contracts entered, amended or extended on or after July 1, 2025) lets a business show a retention offer only if a "click to cancel" button stays on screen beside it and cancelling is then processed promptly. Not legal advice. A small seller who bills with PayPal Subscriptions has no ready subscriber cancel page that does this: Kajabi says "PayPal cancellations finish outside of Kajabi", and Churnkey's native billing providers are Stripe, Chargebee, Paddle and Braintree. PayPal provides the pieces (suspend, activate, cancel, refund) but not the subscriber screen. We built that screen.

What it does

A fictional seller, Clay Studio, sells a $9 per week pottery class pass on PayPal Subscriptions. When the subscriber presses Cancel:

  • "Cancel now" and the line "If you cancel now: refund $X" are on screen before anything else and stay in the same place in every state.
  • The subscriber may type a reason. An AI agent picks at most one offer: a pause (2, 4, 6 or 8 weeks, from the merchant's menu) or no offer. There is no discount, coupon or price change anywhere in the code.
  • Pause is a PayPal suspend; FairCancel calls activate on the resume date. Cancel now is a PayPal cancel, and the unused days are refunded through PayPal by server code, for example $9.00 x 5.99 of 7 days unused = $7.70. If no class was attended this week, the full payment goes back.
  • A paused subscriber can resume in one click; a Sync button re-reads PayPal.
  • A merchant dashboard shows the keyword rule card next to the agent's pick, every PayPal call in an Activity list, and the sandbox evidence.

How we built it

Node.js, Express, React 19, Vite and zod. All PayPal calls go through one gateway that also writes the Activity list: Subscriptions API (read state, transactions, suspend, activate, cancel), the v2 captures refund endpoint, and the PayPal Agent Toolkit (show_subscription_details, cancel_subscription, create_refund). Money moves only in server code, under a per-subscription lock, with a PayPal-Request-Id so one request never refunds twice. The refund is floor(amount x unused time / 7 days) from the latest completed payment.

The AI is Claude Sonnet (claude-sonnet-5-5) with seven tools (get_subscription_state, list_recent_payments, get_usage_record, get_policy, quote_refund, propose_offer, answer_subscriber). None of them can pause, cancel or refund. The model reads a return time out of free text, including sentences keywords cannot read ("Back after the holidays, my kid is home"), and proposes a pause length. The server checks it against the merchant menu, drops quoted words that are not the subscriber's own, and throws away any dollar figure that is not its own. Cancel now never waits for the model.

The hosted demo calls Claude live with per-IP-hour and per-day caps. When the API fails, is too slow or a cap is hit, the action still finishes: the page shows a labelled recorded Claude run or a rule-based stand-in, and says so on screen.

The rule that cannot be switched off lives in one frozen object (STATE_RULE_LAYER, tagged CA-BPC-17602-e2); the merchant layer (pause menu, refund mode) is validated separately and cannot touch it.

Built during the hackathon period: planning files and code are dated Nov 11-12, 2026.

Challenges we ran into

  • PayPal gives no resume date on suspend, so we schedule activate ourselves.
  • PayPal has no automatic pro-rata refund on cancel, so a calculator in code does it, and we checked that a subscription transaction ID works as a v2 capture ID (it did, refund 201).
  • After a refund, the capture shows no refunded total (check V14 failed). A refund whose answer was lost therefore ends as "refund by hand" and never sends a second refund.
  • The first account-mode model timeout cut off every decision; we measured 5 to 16 s per decision in that mode and made the timeout longer while keeping Cancel now independent of it.
  • We kept each of these visible in the README instead of hiding them.

Accomplishments that we're proud of

  • The whole judge page was walked on real sandbox subscriptions: cancel 204, suspend 204, activate 204, refund 201, and the refund IDs shown on screen read back COMPLETED from the PayPal API (5 of 5 statuses and 2 of 2 refunds matched, 0 mismatches).
  • A real BILLING.SUBSCRIPTION.CANCELLED webhook reached the hosted server, passed verify-webhook-signature, and the server re-read the subscription from PayPal; an unsigned forged POST got 401.
  • Cancel now sits at the same screen position in every step of the walk, and the AI has no tool that can move money.
  • Every claim in the docs is tied to a numbered check in VERIFY.md, including the ones that failed or are still open.

What we learned

A retention offer is only trustworthy when the "leave" path is fixed in code, not in a prompt. Letting the model only propose, and having the server validate and execute, gave us both a flexible agent and a hard guarantee. We also learned how PayPal Subscriptions behaves in the sandbox: suspend then activate keeps the billing date and charges nothing, and a suspended subscription can be cancelled directly.

What's next for FairCancel

(1) A New York layer (General Business Law 527-a) and a New York City layer, picked by the subscriber's state, with the strictest layer winning. (2) The same tools and pause menu for other weekly or monthly memberships on PayPal Subscriptions (gyms, tutoring, software seats). (3) A hosted "cancel and pause" page that a seller turns on from the PayPal dashboard instead of running a server. None of these is built today. Still open: confirming the 7-day weekly renewal in the sandbox, and measuring latency on the hosted API model path.

Built With

Share this project:

Updates

Submission history