How to add a cancel flow to Chargebee
Building a cancel flow on Chargebee: portal cancellation settings, reason codes, the cancel API, scheduled cancellations, and offers that save customers fairly.
By Florian
Chargebee gives you a lot of control over how a subscription ends: when the cancellation takes effect, what happens to credits, whether a reason is required, and whether customers can do it themselves. What it does not give you by default is a flow: a short sequence that asks why the customer is leaving and offers something useful before they go.
This guide shows how cancellation works in Chargebee Billing, which settings matter, and how to build a fair cancel flow on top, either with Chargebee’s own retention product or your own page and the API. It sticks to Chargebee’s documentation: Subscription Cancellation, the Self-Serve Portal, Reason Codes, the Cancel a subscription API, event types and Chargebee Growth’s targeted offers use case (all accessed November 2026).
How cancellation works in Chargebee
Site-wide defaults
Chargebee’s cancellation docs put the defaults under Settings › Configure Chargebee › Billing LogIQ › Customers & Subscriptions › Subscription cancellation. There you set:
- When it takes effect: immediately, at the end of the current term, on a specific date, or at the end of the billing term.
- What happens to unused time: how credits are handled.
- Overrides: “Allow overriding via Chargebee interface” lets your team change the default case by case, and “Add condition to this rule” lets the behavior differ by channel (web interface, API, Self-Serve Portal, scheduled cancellations).
End of term: non-renewing
When a cancellation is scheduled for the end of term, the subscription does not end right away. Per the Cancel a subscription API, its status becomes non_renewing and its remaining billing cycles drop to 0. It then cancels at the end of the term. Chargebee sends subscription_cancellation_scheduled when the cancellation is scheduled, a subscription_cancellation_reminder 6 days before it takes effect, and subscription_cancelled when it does (event types).
A non-renewing subscription can still be kept. Chargebee has a “Remove scheduled cancellation” operation for exactly that case.
Contract terms
For subscriptions on a contract term, the cancellation docs say a cancellation from the Self-Serve Portal happens at the end of the contract term only. In the API, these subscriptions use contract_term_cancel_option instead of cancel_option.
Letting customers cancel themselves
In the Self-Serve Portal settings, “Allow customers to cancel subscription” turns self-service cancellation on. You choose when it takes effect: immediately, at the end of the term, or let customers choose (in which case they can also pick a date within the subscription period). The same section includes optional feedback collection, reactivation, and removal of scheduled cancellations.
Turn it on. Making customers email support to cancel creates friction that shows up as chargebacks and angry reviews, and in many places the law now expects cancellation to be as easy as signing up.
Reason codes
Chargebee has a native list of cancellation reasons. You configure it under Settings › Configure Chargebee › Reason Codes › Subscriptions › Subscription Cancellation (Reason Codes). The codes then appear as choices when a subscription is cancelled from the Chargebee interface or the Self-Serve Portal, and you can make them mandatory.
In the API, the Cancel a subscription endpoint takes cancel_reason_code: a case-sensitive string, up to 100 characters, that must match one of the configured codes, and that must be passed if you made reasons mandatory.
Keep the list short and actionable. Six to eight reasons that each map to a different response beat twenty that nobody reads:
| Reason code | What you can offer |
|---|---|
| Too expensive | A discount for a few months, or a cheaper plan |
| Not using it enough | A pause, or a smaller plan |
| Taking a break / seasonal | A pause with a resume date |
| Missing a feature | Nothing to buy; log it and say if it is planned |
| Switching to another tool | Nothing; ask what they chose and let them go |
| Technical problems | A fast route to support |
| Other | Free text |
Building the flow
Option 1: Chargebee’s own retention product
Chargebee offers cancel-page offers through Chargebee Growth (which absorbed the product previously called Chargebee Retention). Its targeted offers use case describes three offers on a cancel page: a discount (tied to a coupon in Chargebee Billing), a pause, and a plan downgrade, applied in Billing when the customer accepts. It also notes that subscribers without a stored payment method cannot complete the change or resume automatically after a pause. If you already pay for Growth, start there.
Option 2: your own page and the API
If you prefer your own page, the building blocks are all in Chargebee Billing:
- Intercept the cancel button in your app. Show your own page before anything is cancelled.
- Ask for the reason. One question, using your Chargebee reason codes as the options.
- Show one offer that fits the reason, or none. Use a coupon for discounts, the pause API for breaks, or a plan change.
- Keep “Cancel my subscription” visible on every step. One click, no extra screens.
- Cancel with the reason. Call the cancel endpoint with
cancel_optionset toend_of_term(orcontract_term_cancel_optionfor contract subscriptions) and thecancel_reason_code. Note thatend_of_termas a boolean is deprecated in favour ofcancel_option. - Confirm clearly. Show the end date and send a confirmation email.
- Offer a way back. Until the end date, a “Keep my subscription” button that removes the scheduled cancellation.
Using the reason after cancellation
Chargebee notes that cancel_reason_code may not be returned for non-renewing subscriptions by default when you retrieve them; a site-level setting includes it, so you can act on the reason before the cancellation runs (Subscription Cancellation). Turn it on if you want reason-based reminders during the remaining term.
Fairness rules worth keeping
- Cancel is always one click away. An offer is a choice, not a gate.
- No more than one offer. A second offer after a “no” feels like haggling.
- Do not ask for a reason twice. If the customer answered on your page, pass it through; do not make them pick again in the portal.
- Honour the cancellation immediately. If they decline the offer, cancel, confirm, and stop.
Measuring it
Track, per reason: how many customers reached the cancel page, how many accepted an offer, and how many of those were still paying 90 days later. A save that cancels a month later is a delay, not a save. Chargebee’s subscription_cancellation_scheduled and subscription_cancelled events, together with your page’s own logs, give you all three numbers.
Doing this with NoChurn
Cancellation itself stays in Chargebee: NoChurn calls Chargebee to cancel, pause or apply an offer, and Chargebee’s portal keeps working as configured. NoChurn provides the flow: reasons, one offer per reason (discount, pause or plan change), and a one-click cancel that is visible at every step, hosted or headless through the API. Answers feed a churn score from 0 to 100 and win-back emails at day 30, 60 and 90 based on the reason. See NoChurn + Chargebee.