Inspiration
For a small software business, cancellation is one button, and everyone who presses it is treated identically. But "money is tight this month" and "this isn't the right tool for me" are completely different people. One of them you could keep by charging them nothing for sixty days. The other you should let go cleanly, because trapping someone produces chargebacks and disputes that cost far more than the subscription earns.
Today both get the same confirmation screen, and both are gone forever.
Cancel-flow tools exist for other billing systems. We wanted to see what it takes to do it on PayPal subscriptions with an AI making the call — without ever letting that AI do something to someone's money that PayPal or the subscriber did not allow.
What it does
Fermata has two sides, and both are live.
The subscriber's cancel page. The subscriber says why they are leaving in their own words and gets one considered offer back: pause, a smaller plan, or a clean goodbye. They accept it or decline it. "Cancel anyway" is always there and is never a model decision.
The retention desk. The business sees each subscriber's live PayPal state, what subscribers did on their cancel pages as it happens, and a receipt for every PayPal call — HTTP status, state change, PayPal's debug ID.
Behind both, the server pulls live subscription state from PayPal, computes the actions PayPal will genuinely permit right now, and asks Gemini to choose one and justify it. The choice is executed as a real PayPal call.
We measured it: 32 labelled cancellation messages, including four attempts to talk the model into refunds or admin powers, with every row published in the repo (docs/EVAL.md). In the latest run all 32 landed inside the accepted set. The labels are ours and model output varies between runs.
How we built it
- PayPal Subscriptions, Billing Plans and Catalog Products are the spine — not a checkout button bolted onto the side. Suspend, activate, revise, cancel and the transactions endpoint are all driven directly.
- Google Gemini (
gemini-flash-latest) makes the decision, using structured output with a response schema so the verdict is a typed object rather than prose to be parsed. - No dependencies. The server is Node's standard library only, so there is no install step and nothing in the tree can rot before judging.
- No database. PayPal is the source of truth; the app holds only a registry of subscription IDs.
The design rule we're proudest of
The model never invents a PayPal call.
The server computes the permitted action set. The model may only select from that menu. If it returns anything else, the pick is rejected and the case is escalated to a human — and the UI renders the menu as a ballot, so you can see exactly what it was allowed to choose from and what it picked.
The decision is then held server-side under a single-use id, and the execute endpoint accepts only that id — never an action name. A hallucinated payment action isn't merely discouraged here; neither the model nor the browser has a way to express one.
Changing someone's plan takes their consent
When Fermata decides on a downgrade, PayPal's revise call does not apply it — it returns an approval link for the subscriber, and Fermata surfaces that link instead of pretending the job is done.
We want to be exact about this, because we tested the edges: the consent step applies to moving a subscriber to a different plan. PayPal does allow a merchant to patch a subscription's price server-side without approval. Fermata never puts that on the menu. That restraint is ours, by design.
The retention prompt also instructs the model that "release" is a correct outcome — a retention tool that cannot say goodbye is just a dark pattern with a language model attached.
Challenges we ran into
Indian sandbox accounts can't do subscriptions. Our first merchant account was created in India, and every subscription approval died on a generic PayPal error. Rebuilding on US sandbox accounts fixed it. It's written up in the README so the next person loses zero hours to it.
revise stages a change; it doesn't make one. It returns an approval link, and until the subscriber approves, the subscription carries hidden pending state. A subscription paused in that state could not be reactivated — SESSION_STATE_NOT_VALID: "Buyer has not agreed to subscription" — and it couldn't be revised back either, because revise is rejected once the status is SUSPENDED.
And the pending state isn't visible in the API: we compared a pending subscription against a clean one and found the same fields, links and plan_id. So Fermata records outstanding consent itself — in the subscription's custom_id on PayPal, so it survives a restart — and takes "pause" off the menu while it is outstanding. We found all of this in the sandbox by stranding a test subscriber and having to replace them.
What we learned
That the interesting constraints in payments are the ones the API enforces on you. We set out to let an agent manage subscriptions, and PayPal kept saying "not without the human's consent." Rather than route around that, we made it the product's spine.
What's next
Failed payments: subscriptions that end because a card was declined, where the subscriber never asked to leave. We did not build this — the sandbox gave us no way to put an unpaid balance on a subscription to test against. The route is the BILLING.SUBSCRIPTION.PAYMENT.FAILED webhook and PayPal's capture endpoint. After that: outcome tracking to learn which interventions actually hold, and per-merchant policy so the permitted action set reflects the business's own rules.
Tools used
- PayPal REST APIs (sandbox): Catalog Products, Billing Plans, Subscriptions (create, suspend, activate, revise, cancel, transactions, custom_id), OAuth2.
- Google Gemini (
gemini-flash-latest, fallbackgemini-3.1-flash-lite): makes the retention decision as structured JSON, constrained to a server-computed menu. - Claude Code: AI coding assistant used to help build and test the project.
Try it
Live demo: https://fermata-535c.onrender.com (the free host sleeps when idle, so the first load can take up to a minute).
- On the desk, pick a subscriber and open their cancel page.
- Give a reason and accept the offer.
- Back on the desk you'll see what the subscriber did and the PayPal receipt: HTTP status, state change and debug ID.
- "Resume everyone who is paused" puts things back.
Pause and resume execute for real and can be undone. Cancelling and plan changes are decided but not executed on the shared demo, because one cannot be undone and the other waits on the subscriber; both run for real in your own copy (see the README).