Docs

Paddle.Retain.initCancellationFlow()

Use to start 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.

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

subscriptionIdstring
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

statusstring
Status of the cancellation flow.
Values
  • aborted
    Customer started the cancellation flow, but chose not to cancel by clicking the 'Never mind, I don't want to cancel' option.
  • chose_to_cancel
    Customer started the cancellation flow, rejected salvage attempts and salvage offers, and proceeded to cancel.
  • retained
    Customer started the cancellation flow, and accepted a salvage attempt or a salvage offer. They did not cancel.
  • error
    There was a problem starting the cancellation flow.
salvageAttemptResultobject | null
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.
decisionstring
Whether the customer decided to accept or reject salvage attempts.
Values
  • accepted
    Customer accepted a salvage attempt.
  • rejected
    Customer rejected a salvage attempt.
resolutionstring
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.
Values
  • accepted
    Salvage attempt prevented a customer from canceling.
  • rejected
    Customer chose to cancel.
hasErrorsboolean
Whether the salvage attempt encountered an error. For example, there was a problem pausing a subscription.
salvageOfferResultobject | null
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.
decisionstring
Whether the customer decided to accept or reject a salvage offer.
Values
  • accepted
    Customer accepted a salvage offer.
  • rejected
    Customer rejected a salvage offer.
hasErrorsboolean
Whether the salvage offer encountered an error. For example, there was a problem applying a discount.
additionalFeedbackstring | null
Additional feedback left by the customer. null if no feedback or not presented to the customer.
cancelReasonstring | null
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.
Values
  • Not useful right now
    Customer selected the 'Not useful right now' option. Designed to be the inverse of the 'Many things, I'll be back' option in question 2.
  • Didn't see the value
    Customer selected the 'Didn't see the value' option. Designed to be the inverse of the 'Good value' option in question 2.
  • Poor support
    Customer selected the 'Poor support' option. Designed to be the inverse of the 'Helpful support' option in question 2.
  • Missing features/hard to use
    Customer selected the 'Missing features/hard to use' option. Designed to be the inverse of the 'Easy to use' option in question 2.
  • Other
    Customer selected the 'Other' option. Designed to be the inverse of the 'Other' option in question 2.
satisfactionInsightstring | null
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.
Values
  • Many things, I'll be back
    Customer selected the 'Many things, I'll be back' option. Designed to be the inverse of the 'Not useful right now' option in question 1.
  • Good value
    Customer selected the 'Good value' option. Designed to be the inverse of the 'Didn't see the value' option in question 1.
  • Helpful support
    Customer selected the 'Helpful support' option. Designed to be the inverse of the 'Poor support' option in question 1.
  • Easy to use
    Customer selected the 'Easy to use' option. Designed to be the inverse of the 'Missing features/hard to use' option in question 1.
  • Other
    Customer selected the 'Other' option. Designed to be the inverse of the 'Other' option in question 1.
salvageAttemptIntendedstring | null
Salvage attempt presented to the customer based on their satisfaction insight. null if customer chose not to cancel or closed the modal.
Values
  • contact_support_email_notification
    Presented where the satisfaction insight is 'Other'. Customer is prompted to send a message to your support team to chat more about this.
  • contact_support_meeting_scheduler
    Presented where the satisfaction insight is 'Helpful support'. Customer is prompted to schedule a meeting using Calendly.
  • pause_subscription
    Presented where the satisfaction insight is 'Many things, I'll be back'. Customer is prompted to pause their subscription for three months.
  • plan_switch
    Presented where the satisfaction insight is 'Good value, I'll be back'. Customer is prompted to switch to another plan.
salvageAttemptUsedstring | null
Salvage attempt accepted by the customer. null if customer chose not to cancel, closed the modal, or does not accept a salvage attempt.
Values
  • contact_support_email_notification
    Presented where the satisfaction insight is 'Other'. Customer is prompted to send a message to your support team to chat more about this.
  • contact_support_meeting_scheduler
    Presented where the satisfaction insight is 'Helpful support'. Customer is prompted to schedule a meeting using Calendly.
  • pause_subscription
    Presented where the satisfaction insight is 'Many things, I'll be back'. Customer is prompted to pause their subscription for three months.
  • plan_switch
    Presented where the satisfaction insight is 'Good value, I'll be back'. Customer is prompted to switch to another plan.

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 isn't 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.

HTML
<!-- Cancellation button -->
<button onclick="cancelSubscription()">Cancel my subscription</button>


<script type="text/javascript">
  function cancelSubscription() {
    Paddle.Retain.initCancellationFlow({
      subscriptionId: "sub_01h8bqcrwp0vjd1p3bv20y7323",
    });
  }
</script>
TypeScript
import { initializePaddle } from "@paddle/paddle-js";


const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08",
});


paddle?.Retain.initCancellationFlow({
  subscriptionId: "sub_01h8bqcrwp0vjd1p3bv20y7323",
});

To learn more, see Build cancellation surveys and offers

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 chose not to cancel.
  • There was a problem starting the cancellation flow.
    Something went wrong while starting the cancellation flow. The customer wasn't given the chance to cancel.
  • Customer proceeded with cancellation.
    The customer rejected salvage attempts and salvage offers and proceeded to cancel.
HTML
<!-- Cancellation button -->
<button onclick="cancelSubscription()">Cancel my subscription</button>


<script type="text/javascript">
  // Cancel subscription
  function cancelSubscription() {
    Paddle.Retain.initCancellationFlow({
      subscriptionId: "sub_01h8bqcrwp0vjd1p3bv20y7323",
    })
      .then((result) => {
        if (result.status === "retained" || result.status === "aborted") {
          console.log("Customer retained!");
        } else if (result.status === "error") {
          console.log("There was a problem starting the cancellation flow.");
        } else {
          console.log("Customer proceeded with cancellation.");
        }
      })
      .catch((error) => {
        console.error(error);
      });
  }
</script>
TypeScript
import { initializePaddle } from "@paddle/paddle-js";


const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08",
});


paddle?.Retain.initCancellationFlow({
  subscriptionId: "sub_01h8bqcrwp0vjd1p3bv20y7323",
})
  .then((result) => {
    if (result.status === "retained" || result.status === "aborted") {
      console.log("Customer retained!");
    } else if (result.status === "error") {
      console.log("There was a problem starting the cancellation flow.");
    } else {
      console.log("Customer proceeded with cancellation.");
    }
  })
  .catch((error) => {
    console.error(error);
  });

To learn more, see Build cancellation surveys and offers

Was this page helpful?