Paddle.Retain.initCancellationFlow()
Starts a Paddle Retain cancellation flow for a subscription.
Use Paddle.Retain.initCancellationFlow() to start a Paddle Retain cancellation flow for a subscription.
Cancellation Flows help you save customers from canceling by presenting them with dynamic salvage attempts while gathering cancellation insights. Retain automatically schedules a cancellation for the subscription in Paddle Billing if a customer proceeds to cancel.
Typically used as part of a cancel subscription workflow.
Only available for live accounts. Paddle Retain works with live data only, meaning this method is only available for live accounts. Paddle Retain is not loaded at all for sandbox accounts.
This method is for Paddle Billing only. If you use Cancellation Flows with another billing platform, use the
profitwellmethod in the Profitwell.js snippet instead. See: Configure Cancellation Flows and salvage offers
To specify a subscription to cancel, pass a subscriptionId parameter. This is recommended, but not required where customers only have one subscription and you passed pwCustomer to Paddle.Initialize() or Paddle.Update().
Parameters
Paddle ID of the subscription to cancel. Required where a customer has multiple subscriptions and where pwCustomer has not been passed to Paddle.Initialize() or Paddle.Update(). Paddle Billing only.
Returns
Status of the cancellation flow.
Information about the salvage attempts that the customer was shown. null if salvage attempts not presented, like if they chose not to cancel or closed the modal.
Whether the customer decided to accept or reject salvage attempts.
Whether the customer chose to cancel. Customers may accept a salvage attempt but still choose to cancel. For example, customers may choose to accept a contact support salvage attempt, but still proceed to cancel their subscription.
Whether the salvage attempt encountered an error. For example, there was a problem pausing a subscription.
Information about the salvage offer that the customer was shown. null if salvage offers not presented, like if they chose not to cancel or closed the modal.
Whether the customer decided to accept or reject a salvage offer.
Whether the salvage offer encountered an error. For example, there was a problem applying a discount.
Additional feedback left by the customer. null if no feedback or not presented to the customer.
Reason for cancellation left by the customer. This is the first question on the survey presented to the customer. null if customer chose not to cancel or closed the modal.
Satisfaction insight selected by the customer. This is the second question on the survey presented to the customer. null if customer chose not to cancel or closed the modal.
Salvage attempt presented to the customer based on their satisfaction insight. null if customer chose not to cancel or closed the modal.
Salvage attempt accepted by the customer. null if customer chose not to cancel, closed the modal, or does not accept a salvage attempt.
Examples
This example shows how you can use Paddle.Retain.initCancellationFlow() to start a cancellation flow.
subscriptionId is passed to Paddle.Retain.initCancellationFlow() to specify the subscription to cancel.
pwCustomer is passed to Paddle.Initialize() to identify the customer to Paddle Retain, but this is not required. Paddle Retain infers the customer from the subscriptionId passed and presents a cancellation flow.
Retain automatically schedules a cancellation for the subscription in Paddle Billing if a customer proceeds to cancel, so you don't need to build logic to handle this yourself.
123456789101<!-- Cancellation button -->
2<button onclick="cancelSubscription();">Cancel my subscription</button>
3
4<script type="text/javascript">
5 function cancelSubscription() {
6 Paddle.Retain.initCancellationFlow({
7 subscriptionId: 'sub_01h8bqcrwp0vjd1p3bv20y7323'
8 });
9 }
10</script>This example shows how you can attach a callback to a cancellation flow.
It uses the .then() method to attach a callback that logs a message to the console:
Customer retained!
The customer accepted a salvage attempt or a salvage offer, or clicked 'Never mind, I don't want to cancel.'
There was a problem starting the cancellation flow.
Something went wrong while starting the cancellation flow. The customer was not given the chance to cancel.
Customer proceeded with cancellation.
The customer rejected salvage attempts and salvage offers and proceeded to cancel.
12345678910111213141516171819201<!-- Cancellation button -->
2<button onclick="cancelSubscription();">Cancel my subscription</button>
3
4<script type="text/javascript">
5 // Cancel subscription
6 function cancelSubscription() {
7 Paddle.Retain.initCancellationFlow({
8 subscriptionId: 'sub_01h8bqcrwp0vjd1p3bv20y7323'
9 })
10 .then((result) => {
11 if (result.status === 'retained' || result.status === 'aborted') {
12 console.log("Customer retained!");
13 } else if (result.status === 'error') {
14 console.log("There was a problem starting the cancellation flow.");
15 } else {
16 console.log("Customer proceeded with cancellation.");
17 }
18 })
19 .catch((error) => {
20 console.error(error);
