How to add a cancel flow to Maxio
How cancellation works in Maxio Advanced Billing: immediate and delayed cancels, reason codes, Billing Portal settings, holds, coupons and product changes.
By Florian
A cancel flow sits between the “Cancel” button and the cancellation: it asks why, makes one offer that fits the reason, and cancels cleanly if the customer still wants to go. Maxio Advanced Billing (formerly Chargify) already has several of the pieces: delayed cancellation, churn reason codes, holds and scheduled product changes. This guide explains how they work and how to put them together into a flow.
It sticks to Maxio’s own documentation: cancelling subscriptions, schedule a subscription cancellation, manage subscriptions in the Billing Portal, configuring Billing Portal features, churn reason codes, on hold and resume scenarios, apply coupons to subscriptions, the update subscription and initiate delayed cancellation API references, and webhook payload examples (all accessed November 2026). Some of Maxio’s API examples still use older Chargify URLs; check the endpoints for your site.
How cancellation works in Maxio
Maxio offers three timings (cancelling subscriptions):
| Timing | What happens |
|---|---|
| Immediately | The subscription is canceled now |
| At the end of the period | It keeps running through the paid period in a Pending Cancellation state, then cancels |
| On a scheduled date | It cancels on a future date you or the customer pick (needs the scheduling feature) |
In every case, Maxio does not refund or prorate automatically. For a customer who chose to leave, end of period is the fair default: they keep what they paid for.
A pending cancellation can be removed: Maxio’s guide to building your own Billing Portal lists a separate endpoint for that. Through the API, a delayed cancellation accepts a reason code and the cancel_at_end_of_period flag; scheduling a date requires the Schedule Subscription Cancellation feature to be enabled on your site.
Some subscriptions cannot be scheduled to cancel. Per Maxio, prepaid subscriptions always cancel immediately, and subscriptions in states such as Past Due, Expired or Paused cannot be scheduled (schedule a cancellation). Your flow has to handle those cases.
Churn reason codes
Maxio has built-in churn reason codes. You create, edit, sort and delete them in your site settings, and they appear when someone cancels from the subscription summary. Once your site has codes configured, a reason must be selected before a cancellation is confirmed. When codes are in use, Maxio’s churn analytics show the reason for each churn event. Use them even if you build your own flow: send the reason code with the cancellation, so Maxio’s reports and yours agree.
The Billing Portal
Maxio’s hosted Billing Portal lets customers cancel from Plan Details, choosing between immediate and end-of-period cancellation (Billing Portal subscriptions). You control it with separate toggles in the Billing Portal features:
- Allow Immediate Cancellations
- Allow Delayed Cancellations (at end of period)
- Allow Scheduling Cancellations, so customers can pick a future date
- Display Churn Reason Codes, so customers pick a reason when they cancel
The portal asks for confirmation, and Maxio notes there is no undo after that step. What the portal does not do is make an offer: it records a reason and cancels. If you want a retention step, put it in your app before the customer reaches the portal, or turn off portal cancellation and handle it yourself. If you keep portal cancellation on, enabling only delayed cancellation is a sensible choice.
The offers Maxio supports
Hold (pause)
Maxio calls a pause a hold (on hold and resume scenarios). While on hold, renewals do not happen. A hold can carry a resume date, and the subscription then resumes on its own (the subscription object has an automatically_resume_at field). Only an Active subscription can be put on hold. One detail matters for cancel flows: a subscription that was set to cancel at the end of the period does not cancel while on hold; it cancels after it resumes.
Maxio’s guide lists hold and resume endpoints, but its own pages show them in two path forms (with and without /subscriptions/:id), so check the current API reference before you build on them.
Coupon
Maxio coupons can be added to an existing subscription (apply coupons). Two rules from the docs:
- The coupon’s duration is counted from the subscription’s next renewal, not from signup.
- A coupon only applies to plans in the same product family.
The pages we found describe adding a coupon in the admin interface; check Maxio’s API reference for the call you will use from your app.
Product change
For “too expensive”, a cheaper plan is often better than a discount. Maxio supports a delayed product change (update subscription): set product_handle to the new product and product_change_delayed to true, and the change happens at the next renewal with no proration. Sending an empty next product cancels a scheduled change. Coupons on the subscription carry over only if they are restricted to the new plan or unrestricted.
Building the flow
- Send “Cancel” in your app to your flow. Decide what the Billing Portal allows, so customers do not reach two different cancellation experiences.
- Check what is possible for this subscription. Prepaid subscriptions cancel immediately; Past Due and Paused ones cannot be scheduled. A hold needs an Active subscription.
- Ask why, using the same list as your Maxio churn reason codes.
- Show one offer that fits. “Too expensive”: a delayed product change or a coupon. “Not using it right now”: a hold with a resume date. “Missing a feature”: a reply from a person.
- Keep “Cancel now” visible on every step. One click finishes the cancellation, without accepting any offer.
- Apply the result. Delayed cancellation with the reason code and
cancel_at_end_of_period; or the hold, coupon or product change. - Confirm the date from the subscription Maxio returns, and offer to undo a pending cancellation until it takes effect.
Webhooks to listen to
From Maxio’s payload examples and webhook events:
subscription_state_changecarriesstateandprevious_state: use it to see a subscription go to canceled, on hold or back to active.pending_cancellation_changehas a sample payload withcancel_at_end_of_periodanddelayed_cancel_at. Maxio’s pages we found do not say exactly when it fires, so test it in your site.
Maxio says webhooks are asynchronous and advises checking that previous_state matches what you have before updating your records, and fetching the subscription from the API when in doubt.
Doing this with NoChurn
NoChurn connects to Maxio with an API key, imports customers and subscriptions and follows Maxio’s webhooks. It adds a cancel flow with reasons, offers that become a coupon or a product change on the Maxio subscription, and a one-click cancel that is always visible, hosted or headless through the API. It also sends win-back emails at day 30, 60 and 90 based on the cancel reason and computes a churn score from 0 to 100. Invoicing, taxes, your products and the charge stay in Maxio and your gateway. NoChurn is free under $300 MRR. See NoChurn + Maxio.