How to add a cancel flow to Braintree subscriptions

Braintree’s recurring billing has a single cancel operation, and it is final: a cancelled subscription cannot be edited or reactivated. There is no built-in cancellation page, no reason survey and no retention offer. If you want customers to see an alternative before they leave, and to keep a record of why they left, you build that flow in your app and call Braintree at the end.

This guide covers the Braintree operations a cancel flow relies on, the limits that shape it, and a step-by-step design. It sticks to Braintree’s own documentation: Subscription: Cancel, Subscription: Update, Manage subscriptions, Plans, Statuses, Subscription webhooks and the subscriptions guide (all accessed November 2026).

How cancellation works in Braintree

Subscription: Cancel moves a subscription to Canceled, which Braintree’s statuses reference describes as no further billing occurring. The reference is explicit that once a subscription is cancelled, you cannot edit or reactivate it; a returning customer needs a new subscription.

Three consequences for your flow:

• Cancel is the last step, never the first. Run every offer before the call.
• There is no “cancel at period end” flag in the cancel operation. If you cancel mid-cycle, billing stops, and what the customer keeps access to is your decision in your app.
• Store the cancellation date yourself. Braintree notes that the cancellation date is not included in subscription search results and suggests capturing it from the subscription_canceled webhook.

Ending at the end of the paid period

Many businesses want the customer to keep access until the end of what they paid for, with no further charge. Two approaches fit Braintree’s model:

1. Cancel now, keep access in your app until the end of the current billing period, using the period end date you stored for the subscription.
2. Limit the number of billing cycles. Subscription: Update lets you set the number of billing cycles, which must be greater than or equal to the current billing cycle, and turns “never expires” off. When a subscription reaches its set number of cycles, Braintree marks it Expired. This lets the subscription end naturally after the current cycle, and a customer who changes their mind before then can be restored by setting it back to never expire.

The second approach keeps the subscription editable until it ends, which makes “undo” easy. Test it in the sandbox with your plan settings before relying on it.

What you can offer instead

Braintree’s update operation gives you the levers for retention offers.

Discounts

You can add, update or remove discounts (and add-ons) on an existing subscription. Key rules from the docs:

• Discount details (name, amount, duration) are managed in the Control Panel, not through the API. Create your retention discounts there first, then apply them by ID.
• A given discount can be applied only once to a subscription; to apply it more than once, use its quantity.

Create a dedicated retention discount, for example “Retention 30% x3”, so accepted offers are easy to find in reports and never confused with sales discounts.

Price and plan changes

You can change the subscription’s price, with a flag that controls whether the change is prorated, or move it to another plan. Braintree notes that switching to a plan with a different billing frequency is only available to select merchants who request it, and resets the current billing cycle. For most cancel flows, a downgrade to a cheaper plan with the same frequency is the simpler offer.

A pause

The Braintree documentation we reviewed does not describe a pause or “skip a cycle” operation for subscriptions. The subscription_billing_skipped webhook exists, but it fires when a cycle is skipped because a zero or negative balance already covers it, not on request. If you want to offer a pause, you would build it on top of Braintree (for example with a temporary full discount for a set number of cycles), and test the billing behaviour carefully first.

Webhooks your flow should listen to

From Braintree’s subscription webhooks:

Kind	Use in a cancel flow
subscription_canceled	Record the cancellation date, revoke access when due, start win-back
subscription_expired	The subscription reached its last cycle (for the “limited cycles” approach)
subscription_charged_successfully	Confirms an offer price was charged

Listen even for cancellations you trigger yourself. Support agents can cancel from the Control Panel, and those cancellations should land in the same records.

Building the flow

1. Route the cancel button to your own page, never straight to the API.

2. Ask why. Five to seven reasons plus “Other”. Store the answer with the Braintree subscription ID. Ideas in cancellation reason surveys.

3. Show one offer that matches the reason:

   Reason	Offer	Braintree operation
   Too expensive	Limited-time discount	Update: add a retention discount
   Need less	Cheaper plan	Update: change plan or price
   Not using it right now	A pause, if you have built one	Your own logic (see above)
   Technical problem	Help from support	None until resolved
   Switching or closing	No offer	Cancel

4. Keep “Cancel subscription” visible on every step, as easy to click as the offer. Rules and good practice in click-to-cancel rules and cancel flow best practices.

5. On accept, call Subscription: Update, confirm by email with the new price and how long it lasts.

6. On cancel, call Subscription: Cancel (or limit billing cycles), show the date access ends, send a confirmation.

7. Handle past due subscriptions. A customer cancelling while past due may owe a balance; decide your policy and show it.

8. Review monthly which reasons come up most and which offers are still paying after three months.

Common mistakes

• Cancelling, then trying to apply an offer. Cancelled subscriptions cannot be edited.
• Creating discounts in code. Discount details live in the Control Panel; plan them ahead.
• Losing the cancel date. Without the webhook stored, you cannot time win-back emails or measure churn by month.
• Hiding the cancel option behind the offer. It costs trust and, in many places, breaks the rules.

Doing this with NoChurn

Braintree keeps the subscription, payments and the cancellation itself. NoChurn’s cancel flow asks for the reason, shows an offer (a discount, a plan change or a cancellation on the Braintree subscription), and keeps a one-click cancel visible at every step, hosted or headless through the API. The answers feed win-back emails at day 30, 60 and 90 and a churn score from 0 to 100, and they become evidence if the customer later disputes a charge. See NoChurn + Braintree.