For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Docs

Configure Cancellation Flows

Build a cancellation process that saves customers by presenting them with dynamic salvage attempts, as well as capturing cancellation insights for your team.

AI summary

Configure Cancellation Flows in Paddle Retain to present customers with dynamic salvage attempts and gather cancellation insights when they try to cancel their subscription.

  • • Cancellation Flows are built into the Paddle customer portal by default — you can also build a custom workflow in your frontend using Paddle.js for full UI control.
  • • The flow surveys customers on why they're canceling and presents curated salvage attempts like pausing or plan-switching; as a last resort you can offer a discount to prevent churn.
  • • Paddle Billing integration means Cancellation Flows automatically takes action on the related subscription (e.g., applying a pause or downgrade) when a customer accepts a salvage offer.

You can use Cancellation Flows, part of Paddle Retain, to build custom curated off-boarding experiences that are designed to prevent customers from churning.

Cancellation Flows presents customers with a simple survey that suggests dynamic salvage attempts, like pausing a subscription or switching plans, as well as gathering useful insights around why they want to cancel. As a last resort, you can offer customers a discount to incentivize them to stick around.

How it works

Paddle Retain combines world-class subscription expertise with algorithms that use billions of data points to automatically reduce churn. Paddle Billing is fully integrated with Retain, meaning it automatically handles dunning and retention for you.

Cancellation Flows are a part of Paddle Retain, helping you save customers from canceling and gathering cancellation insights. They ask customers why they're canceling, as well as what they found valuable about your app, then presents curated salvage attempts.

If you use Paddle Billing, Cancellation Flows automatically takes action on the related subscription for you. Cancellation Flows are built-in to the customer portal, or you can build your own workflow in your frontend using Paddle.js.

Before you begin

  • Set up Paddle Retain
    If you haven't already, connect Paddle Retain to your billing platform and set up Paddle Retain.
  • Make sure you've installed Paddle.js
    Paddle.js must be installed and verified as installed on a public page on your site. Follow the instructions during setup, click Edit under Paddle.js is not installed, or click Install under Paddle.js is not installed in web app.

Set up Cancellation Flows

Go to Retain

If you set up Retain for Paddle Billing, you can access and configure Cancellation Flows in the Paddle Billing dashboard.

  1. Go to Paddle > Retain in your dashboard.
  2. Click Cancellation Flows .
  3. If setting up for the first time, click Get started . If you’ve already configured Cancellation Flows, click Edit .

Add branding

Branding lets you customize the look and feel of Cancellation Flows, so they fit the style of your app. You can change the font family, and colors for text and components.

  1. Click the field under Brand color and use the color picker to select the color for selected states and progress bars.
  2. Choose the font family for the text from the dropdown under Font.
  3. Click the field under Text color and use the color picker to set the color for text.
  4. Click the field under Selected text color and use the color picker to set the color for text in selected states.
  5. View a preview of the first screen of the flow with your style selections on the right-hand side.
  6. Click Continue to continue to the next step.

Add responses for cancellation reasons

On the first screen of the flow, a customer is asked why they're canceling. You can add up to 5 responses to this question that are displayed as options the customer can select.

  1. Enter the text for each response under the Response fields.
  2. Click Add response to add a new response field.
  3. To remove a response, click the icon next to it.
  4. Check the preview of the first screen of the flow with your added responses on the right-hand side.
  5. Click Continue to move to the next step.

Add responses for cancellation insights

On the second screen of the flow, a customer is asked what they think your app or company is doing well. You can add up to 5 responses to this question that are displayed as options the customer can select.

These response options are also used in the next step to offer a salvage attempt to the customer.

  1. Enter the text for each response in the Response fields.
  2. Click Add response to add another response field.
  3. To remove a response, click the icon next to it.
  4. Preview the second screen of the flow with your added responses on the right-hand side.
  5. Click Continue to move to the next step.

Map responses to salvage attempts

On the third screen of the flow, a customer is offered an alternative option to canceling based on their responses to the previous question.

For each response, you can choose which salvage attempt to offer. There are five types:

TypeDescription
Contact support via emailEncourage customers to email your support team.
Book a meeting with supportEncourage customers to schedule a meeting with your team using Calendly.
Pause planEncourage customers to pause their subscription, so they can come back in the future.
Plan switchEncourage customers to switch to a different product or price, retaining them with an offer that's more suited or affordable.
No attemptDon't offer any salvage attempts. Customers are directed to the next step.

Contact support via email

  1. Select the response you want to offer this salvage attempt for from the dropdown boxes titled When a customer selects.
  2. Select Contact support via email from the dropdown under Offer.
  3. Customize another response's salvage attempt, or click Continue to progress to the next step.

Book a meeting with support

  1. Select the response you want to offer this salvage attempt for from the dropdown boxes titled When a customer selects.
  2. Select Book a meeting with support from the dropdown under Offer.
  3. Enter the text for the copy that precedes "can we chat a bit more about this?" under Header copy.
  4. Customize another response's salvage attempt, or click Continue to progress to the next step.

Pause plan

The number of months to pause the subscription for is automatically set to the number of months remaining on the subscription.

  1. Select the response you want to offer this salvage attempt for from the dropdown boxes titled When a customer selects.
  2. Select Pause plan from the dropdown under Offer.
  3. Enter the text for the copy that precedes "how about pausing your subscription for [x] months?" under Header copy.
  4. Customize another response's salvage attempt, or click Continue to progress to the next step.

Plan switch

  1. Select the response you want to offer this salvage attempt for from the dropdown boxes titled When a customer selects.
  2. Select Plan switch from the dropdown under Offer.
  3. Enter the text for the copy that precedes "how about switching to [x]?" under Header copy.
  4. Customize another response's salvage attempt, or click Continue to progress to the next step.

No attempt

  1. Select the response you want to offer this salvage attempt for from the dropdown boxes titled When a customer selects.
  2. Select No attempt from the dropdown under Offer.
  3. Customize another response's salvage attempt, or click Continue to progress to the next step.

Configure salvage attempts

Once you've mapped responses to salvage attempts, you must configure the salvage attempts you selected.

Contact support via email

  1. Click on the Contact support via email dropdown box.
  2. Enter the email address to direct customers to under Email for customer cancellation updates.
  3. Customize another salvage attempt, or click Continue to progress to the next step.

Book a meeting with support

  1. Click on the Book a meeting with support dropdown box.
  2. Copy your Calendly scheduling link on the Calendly platform.
  3. Enter your Calendly scheduling link under Calendly link.
  4. Customize another salvage attempt, or click Continue to progress to the next step.

Pause plan

  1. Click on the Pause plan dropdown box.
  2. Select the unit of time to pause the subscription for from the dropdown under For.
  3. Enter the number of time units to pause the subscription for in the field under For.
  4. Customize another salvage attempt, or click Continue to progress to the next step.

Plan switch

  1. Click on the Plan switch dropdown box.
  2. Select the plan that customers would be switched from using the dropdown under If customer is on.
  3. Select the plan that customers are offered to switch to using the dropdown under Offer.
  4. Enter any additional details you want to display with the offer under Information to display.
  5. Click Add product to set up another plan switch pairing.
  6. Click the icon next to the Salvage plan dropdown box to remove an existing pairing.
  7. Customize another salvage attempt, or click Continue to progress to the next step.

Customize the final discount offer

Discounts let you reduce the amount a customer pays on subsequent transactions for their subscription. You can optionally offer a one-time, percentage-based discount to encourage customers who reject the salvage attempts to stay.

You can add up to 32 discounts to offer. Customers are offered the discount that matches the billing period of the subscription they are attempting to cancel. If there isn't a discount with a matching billing period, no discount is offered.

You can also set the percentage amount to discount by, and the number of billing periods the discount applies for.

Offer a final discount

  1. Toggle Offer a discount on to enable the final discount offer.
  2. Select the billing period the discount and subscription must match for the discount to be offered from the dropdown under Billing period.
  3. If you selected Every number of days, months, or years, select the time unit from the dropdown and enter the number of time units.
  4. Enter the percentage amount to discount by in the field under Percentage off.
  5. Enter the number of billing periods the discount applies for in the field under Discount length.
  6. Click New discount to add a new discount to match against.
  7. Click to remove an existing discount.
  8. Click Continue to progress to the next step.

Turn off the final discount offer

  1. Toggle Offer a discount off to disable the final discount offer.
  2. Click Continue to finish the flow setup and save your changes.

Customize the final feedback page

If the customer rejects the discount, or if no discount was offered, the customer is sent to the final feedback page to give any final feedback before confirming their cancellation. You can customize the copy on this page to encourage customers to provide feedback and fit your brand.

  1. Enter the text for the page's header copy under Header copy.
  2. Enter the text for the copy following the header under Body copy.
  3. Click Continue to finish the flow setup and save your changes.
  1. Grab a copy of the Paddle Retain Cancellation Flows configuration template and fill it in. If you use Stripe, grab a copy of the Paddle Retain Cancellation Flows configuration for Stripe template and fill it in instead.
  2. Send it to us at sellers@paddle.com.

Preview Cancellation Flows

Once Cancellation Flows are set up, you can preview the flow customers see when they try to cancel a subscription. The flow is interactive, so you can view each page and check how it behaves.

  1. Go to Paddle > Retain > Cancellation Flows.
  2. Click the button in the Cancellation flow card.
  3. Click to preview the flow.

Integrate Cancellation Flows into your frontend

If you handle cancellations using the customer portal, you don't need to do anything. The customer portal automatically launches Cancellation Flows when customers try to cancel a subscription.

If you've built your own cancellation logic outside the customer portal, you need to:

  1. Call the Paddle.Retain.initCancellationFlow() method when a customer tries to cancel a subscription on your website or app, passing the Paddle ID of the subscription entity that the customer wants to cancel.
  2. Attach a callback to build workflows around the result.
  3. Retain automatically handles pausing, applying a discount, switching plans, or canceling the related subscription in Paddle Billing. When those events occur in Paddle, handle provisioning in your app as normal.

Example

Example of a cancellation flow
<!-- Cancellation button -->
<button onclick="cancelSubscription();">Cancel my subscription</button>


<script type="text/javascript">
  function cancelSubscription() {
    Paddle.Retain.initCancellationFlow({
      subscriptionId: 'sub_01h8bqcrwp0vjd1p3bv20y7323'
    });
  }
</script>
  1. Update the cancellation logic in your web app to call the profitwell method, passing init_cancellation_flow and an object containing the ID of the subscription in your billing platform that you want to cancel.
  2. Use the .then() method to attach a callback to the result, then build logic to handle the result. You should cancel a subscription when the customer chooses to cancel or when the cancellation flow encounters an error.
  3. Retain automatically handles pausing, applying a discount, or switching plans in your billing platform. Handle provisioning in your app as normal.

Example

Example of a cancellation flow
<!-- Cancellation button -->
<button onclick="cancelSubscription();">Cancel my subscription</button>


<script type="text/javascript">
  function cancelSubscription() {


    // Any pre-cancellation logic here


    // Start cancellation flow
    profitwell('init_cancellation_flow', {
        subscription_id: 'sub_1OFyRG2eZvKYlo2CQZLEmvPK'
      })
      .then((result) => {
        if (result.status === 'retained' || result.status === 'aborted') {


          // Logic to run when a customer accepts a salvage attempt, salvage offer,
          // or closes the cancellation flow modal.
          console.log("Customer retained!");


        } else {


          // Logic to run when a customer chooses to cancel or when an error occurs.
          console.log("Customer proceeded with cancellation, or an error occurred.");


        }
      });
  };
</script>

Simulate Cancellation Flows

Once you've set up Cancellation Flows, you can simulate one to check how it looks to customers.

  1. Go to a page where you've installed Paddle.js for Retain.
  2. Open your browser console.
  3. Enter Paddle.Retain.demo({feature: 'cancellationFlow'}) .
  1. Go to a page where you've installed the ProfitWell.js snippets.
  2. Open your browser console.
  3. Enter profitwell('cq_demo', 'cancellation_flow') .

Subscribe to notification emails

You can subscribe to receive notification emails based on the outcome of a cancellation flow for monitoring and reporting purposes. You choose which emails you'd like to receive by toggling the available options.

  • Abort Cancellation
    Notify when a customer starts to cancel but is successfully retained and doesn't go through with it.
  • Cancellation
    Notify when a customer completes a cancellation despite going through the flow.
  • Pause Plan
    Notify when a customer accepts a pause offer instead of cancelling.
  • Switch Plan
    Notify when a customer accepts a plan switch as an alternative to cancelling.
  • Salvage Offer
    Notify when a customer accepts a discount or other salvage offer.
  1. Go to Paddle > Retain > Cancellation Flows.
  2. In the Notification email settings section, click Edit .
  3. Enter the email address where you want to receive notifications under Notification email.
  4. Toggle the notification options that you'd like to receive emails for.
  5. Click Save to save your changes.

Subscribe to receive reports

You can subscribe to receive a weekly CSV report of Cancellation Flows activity. The report is an activity log with one row for every time a cancellation flow is initialized. Use it to analyze cancellation patterns, measure your save rate, and identify which salvage attempts are most effective.

Certain fields in the report map to those in the return object of Paddle.Retain.initCancellationFlow().

idinteger
Internal ID for this row.
uuidstring
Unique identifier for this cancellation flow session.
company_idinteger
Identifier for your Paddle account.
customer_idstring
Unique Paddle ID of the customer who triggered the cancellation flow, prefixed with ctm_.
statusstring
Outcome of the cancellation flow session.
Values
  • pending
    The cancellation flow was initialized but hasn't completed yet.
  • aborted
    The customer exited the flow without completing it.
  • retained
    The customer accepted a salvage attempt or discount offer and didn't cancel.
  • chose_to_cancel
    The customer completed the flow and chose to cancel.
created_onstring (date-time)
When the cancellation flow was initialized.
status_last_updatedstring (date-time)
When the status was last updated.
cancel_reason_idstring | null
ID of the cancellation reason the customer selected. Maps to your configured cancellation reasons. Corresponds to the label text returned as cancelReason by Paddle.Retain.initCancellationFlow().
satisfaction_insight_idstring | null
ID of the satisfaction insight the customer selected. Maps to your configured insight responses. Corresponds to the label text returned as satisfactionInsight by Paddle.Retain.initCancellationFlow().
salvage_attempt_intendedstring | null
The type of salvage attempt that was offered to the customer, based on your configuration.
Values
  • contact_support_email_notification
    Customer was prompted to send a message to your support team.
  • contact_support_meeting_scheduler
    Customer was prompted to schedule a meeting using Calendly.
  • pause_subscription
    Customer was prompted to pause their subscription.
  • plan_switch
    Customer was prompted to switch to another plan.
salvage_attempt_usedstring | null
The salvage attempt the customer accepted and engaged with.
Values
  • contact_support_email_notification
    Customer sent a message to your support team.
  • contact_support_meeting_scheduler
    Customer scheduled a meeting using Calendly.
  • pause_subscription
    Customer paused their subscription.
  • plan_switch
    Customer switched to another plan.
salvage_attempt_decisionstring | null
Whether the customer accepted or rejected the salvage attempt, or no attempt was made.
Values
  • accepted
    The customer accepted the salvage attempt.
  • rejected
    The customer rejected the salvage attempt.
  • no_attempt
    No salvage attempt was offered.
salvage_attempt_resolutionstring | null
Whether the salvage attempt successfully prevented the customer from canceling.
Values
  • succeeded
    The salvage attempt prevented the customer from canceling.
  • failed
    The salvage attempt did not prevent the customer from canceling.
salvage_offer_decisionstring | null
Whether the customer accepted or rejected the final discount offer.
Values
  • accepted
    The customer accepted the discount offer.
  • rejected
    The customer rejected the discount offer.
salvage_offer_idstring | null
ID of the discount offer that was presented to the customer.
subscription_idstring
Paddle ID of the subscription the cancellation flow was triggered for, prefixed with sub_.
additional_feedbackstring | null
Free-text feedback provided by the customer on the final feedback page before confirming cancellation.
plan_map_idstring | null
ID of the plan map configuration used for a plan switch salvage attempt.
salvage_attempt_contextstring | null
Additional context about the salvage attempt outcome, as a JSON string.
mrr_cents_at_riskinteger
Monthly recurring revenue at risk from this cancellation, in cents, in the subscription currency.
currencystring
Three-letter ISO 4217 currency code for the subscription.
plan_idstring
Paddle ID of the price the customer was subscribed to, prefixed with pri_.
one_click_cancellationinteger
Whether the customer used one-click cancellation. 1 if true, 0 if false.
  1. Go to Paddle > Retain > Cancellation Flows.
  2. Click Edit in the Weekly report email section.
  3. Enter the email address you want to receive the report at.
  4. Add more email addresses by clicking Add email .
  5. Click Save .

Was this page helpful?