How to add a cancel flow to GoCardless subscriptions

A Direct Debit customer who wants to leave has two ways out: your app, or their bank. If your app makes it hard, the bank is one phone call away, and a cancelled mandate or an indemnity claim is a worse ending for both of you than a clean cancellation. A good cancel flow on GoCardless is therefore partly about keeping customers and partly about making sure the ones who leave do it through you.

This guide shows what GoCardless’s Subscriptions API lets you do when a customer wants to cancel, and how to build a short cancel flow on top of it. It sticks to GoCardless’s documentation: the subscriptions API reference, the subscription events reference and the developer guide Responding to mandate events (all accessed November 2026). GoCardless’s documentation site was not reachable from our research environment, so we checked endpoint behaviour against GoCardless’s official API client libraries, such as gocardless-pro-ruby, which are generated from the same API schema and carry the same descriptions.

What GoCardless gives you

A GoCardless subscription creates payments on a mandate according to its schedule. Its status is one of:

Status	Meaning
pending_customer_approval	Waiting for customer approval
customer_approval_denied	The customer did not approve it
active	Will keep creating payments
paused	Will not create payments
finished	All scheduled payments have been created
cancelled	Will no longer create payments

The four calls a cancel flow needs:

Cancel

POST /subscriptions/:id/actions/cancel immediately cancels the subscription; no more payments are created under it. It fails with cancellation_failed if the subscription is already cancelled or finished.

A payment that was already created can only be cancelled while its status is pending_submission (POST /payments/:id/actions/cancel). Once it has been submitted to the banks, it will be collected or fail on its own. Check upcoming payments when you confirm the cancellation, so you do not promise “no further payments” when one is already on its way.

Pause and resume

POST /subscriptions/:id/actions/pause stops the subscription from creating payments:

• Without pause_cycles, it is paused until you call resume.
• With pause_cycles, it is paused for that number of cycles, and upcoming_payments still shows the later charge dates.
• It works for subscriptions that run forever or collect a fixed count of payments, not for those with an end_date. It fails with subscription_cannot_be_paused when pausing is not possible.

POST /subscriptions/:id/actions/resume restarts payment creation. The next payment’s charge date is the subscription’s earliest_charge_date_after_resume.

This makes “pause instead of cancel” a native offer on GoCardless, which is not the case on every payment platform.

Update

PUT /subscriptions/:id changes fields such as the amount. GoCardless documents limits that matter for discount offers:

• It fails with number_of_subscription_amendments_exceeded if the amount has already been changed 10 times.
• It fails with mandate_payments_require_approval if the amount changes and the mandate requires approval.
• It fails with subscription_not_active if the subscription is no longer active.

A temporary discount therefore costs two amendments (down, then back up). Keep count.

Leave the mandate alone

Cancelling a subscription does not cancel the mandate. GoCardless’s developer guide says to cancel a mandate only if the customer has explicitly asked for it. Keeping it means a returning customer can restart without setting up a new Direct Debit. If the customer asks you to cancel the Direct Debit itself, do it, and say so in the confirmation.

Designing the flow

1. Ask why

One question, a short list, one tap:

• Too expensive
• Not using it enough
• Only needed it for a while
• Missing something
• Moving to another provider
• Other

Store the reason with the customer. You can also put it in the subscription’s metadata before cancelling, so it stays with the GoCardless record.

2. One offer that fits the reason

Reason	Offer	On GoCardless
Only needed it for a while	Pause for 1 to 3 cycles	pause with pause_cycles
Too expensive	A lower price for a few months	update the amount, schedule the update back (2 amendments)
Not using it enough	A cheaper plan	update the amount, or cancel and create a new subscription on the same mandate
Missing something, moving away	No discount; ask for detail	Nothing to change

State the exact effect before the customer accepts: for a pause, the date of the next charge; for a discount, the reduced amount, how many payments it covers and the amount after.

3. Cancel, always visible

The cancel button belongs on every step, not after the offer. A customer who declines the offer is one click away from the confirmation, which says:

• the subscription is cancelled;
• whether any payment already submitted will still be collected, and its date;
• until when they keep access;
• whether the Direct Debit mandate stays in place (and how to cancel it too if they want).

That last point matters on Direct Debit. A customer who sees a mandate still listed at their bank may cancel it there “to be sure”. That is their right, and it is better that they know it is not needed.

Wiring it up

1. Load the subscription and its upcoming payments when the flow opens.
2. Use an idempotency key on pause, resume and cancel calls (GoCardless’s official client libraries handle idempotency conflicts on these actions), and disable buttons after the first click.
3. Listen to subscription events (see the events reference for the full list of actions) so your app stays in sync when changes come from the dashboard or GoCardless itself, for example when a mandate is cancelled and its subscriptions with it.
4. Schedule the follow-ups your offers need: the update back to full price, the end of an indefinite pause, a reminder before a paused subscription restarts.
5. Log every step: reason, offer shown, answer, cancellation time. If an indemnity claim arrives later, this record helps you understand what went wrong.

Measure the right thing

• Offers accepted, by reason.
• Paused subscriptions that resume and are still paying three months later.
• Cancellations through your flow compared with mandates cancelled at the bank. If many customers leave through their bank, the cancel option is too hard to find.

Doing this with NoChurn

GoCardless keeps the subscription, the mandate and collection. NoChurn adds the cancel flow: reasons, an offer that fits each reason and a one-click cancel that is always visible, hosted by NoChurn or built into your own interface with the headless API. On GoCardless, a cancellation ends the GoCardless subscription and the mandate stays as the customer chooses. Cancel reasons drive win-back emails at day 30, 60 and 90 and feed the churn score. See NoChurn + GoCardless.