Paddle

Everything below goes in the options object of the launch call.

Launch methods on Paddle

Every method reads the shared options: handleAbandon, handleClose, handleDone, record, email, language, font, fontUrl and customTexts.

The subscription walls are not supported on Paddle: they need a Stripe setup intent and Stripe.js.

SDK options

fontUrl: 'https://fonts.googleapis.com/css2?family=Roboto'

customerAttributes: {
  Has_Extended_Free_Trial: true
}

customTexts: {
  'Back': 'Retour'
}

cancellationSettings: {
  settings: {
    CANCEL_TIME: {
      cancellation_time_type: 'IMMEDIATE'
    }
  }
}

cancellationSettings: {
  settings: {
    CONFIRM_NOT_CANCELLED_ON_ABANDON: {
      active: false
    }
  }
}

cancellationSettings: {
  uncancel_message: 'Welcome back!'
}

cancellationSettings: {
  unpause_message: 'Welcome back!'
}

pauseSettings: {
  subscriptionEndDate: '2027-04-15'
}

Full example

A run() call that sets every option it reads:

document.getElementById('cancel-button').addEventListener('click', function () {
    window.churnSolution?.run({
        authKey, // hash generated by your server
        subscriptionId, // your subscription ID from your payment provider
        appId: 'APP_ID', // your App ID
        options: {
            record: true, // default true, switch to false to turn off recording
            email: '[email protected]', // User email that initiates the cancel flow
            font: 'Roboto',
            fontUrl: 'https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap',
            language: 'de',
            customerAttributes: {
                Has_Extended_Free_Trial: false,
            },
            customTexts: {
                "Back": "Zurück",
                "Next": "Weiter",
            },
            cancellationSettings: {
                settings: {
                    CANCEL_TIME: {
                        cancellation_time_type: 'END_OF_BILLING_PERIOD', // 'IMMEDIATE' | 'END_OF_BILLING_PERIOD'
                    },
                    CONFIRM_NOT_CANCELLED_ON_ABANDON: {
                        active: true, // show the modal when the customer leaves early
                    },
                },
            },
            pauseSettings: {
                subscriptionEndDate: '2027-04-15', // latest resume date the customer can pick
            },
            handleCancel: (customer, cancelFlowInfo) => {
                // cancel callback
            },
            handleAbandon: (customer, cancelFlowInfo) => {
                // abandon callback
            },
            handleDone: (customer, cancelFlowInfo) => {
                // success screen closed callback
            },
            handleClose: (customer, cancelFlowInfo) => {
                // modal closed callback
            },
            handlePause: ({pausePeriod}, customer, cancelFlowInfo) => {
                // pause callback
            },
            handleCoupon: ({code}, customer, cancelFlowInfo) => {
                // coupon/discount callback
            },
            handleTrialExtension: ({trialExtensionDays}, customer, cancelFlowInfo) => {
                // trial extension callback
            },
            handleSwitchPlan: ({plan}, customer, cancelFlowInfo) => {
                // switch plan callback
            },
            handleSwitchPlanWithCoupon: ({plan, code}, customer, cancelFlowInfo) => {
                // switch plan with coupon callback
            },
            // Default true. Set any of these to false to make
            // the matching handler responsible for the action
            autoCancel: true,
            autoPause: true,
            autoCoupon: true,
            autoTrialExtension: true,
            autoSwitchPlan: true,
            autoSwitchPlanWithCoupon: true,
        },
    });
});

Add custom fonts

By default, Churn Solution uses the font selected on the design page. However, you can override this with any font you prefer for your cancellation flow. To do this, pass two parameters to the sessions API: font and fontUrl.

document.getElementById('cancel-button').addEventListener('click', function () {
    window.churnSolution?.run({
        authKey, // hash generated by your server
        subscriptionId, // your subscription ID from your payment provider
        appId: 'APP_ID', // your App ID
        options: {
            record: true,
            email: '',
            font: 'Roboto', // Font example
            fontUrl: 'https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap', // Font URL example
        },
    });
});

Enable / disable session recording

Session recording is enabled by default. You have the option to disable session recording by setting the record parameter to false in the options of the launch call from the installing section.

window.churnSolution?.run({ authKey, subscriptionId, appId: 'APP_ID', options: { record: false } });

Set cancellation term

Learn how Churn Solution manages the cancellation of your customers' subscriptions. By default, each flow follows the option saved on the configuration page.

• Immediate: choose this option for instant subscription cancellation. The customer's subscription is terminated immediately upon cancelling.
• End of billing period: select this option to handle cancellations at the end of the current billing period. Customers keep access until the end of their paid subscription duration.

document.getElementById('cancel-button').addEventListener('click', function () {
    window.churnSolution?.run({
        authKey, // hash generated by your server
        subscriptionId, // your subscription ID from your payment provider
        appId: 'APP_ID', // your App ID
        options: {
            cancellationSettings: {
                settings: {
                    CANCEL_TIME: {
                        cancellation_time_type: 'IMMEDIATE',
                    },
                },
            },
        },
    });
});

Values are case-sensitive. Custom is supported on Stripe only. On Paddle, Churn Solution drops a 'CUSTOM_DATE' override and uses the stored term. End of billing period is not supported on WooCommerce or Recurpay.

Example: cancel trial users immediately and everyone else at the end of the period:

options: {
    cancellationSettings: {
        settings: {
            CANCEL_TIME: {
                cancellation_time_type: isOnTrial ? 'IMMEDIATE' : 'END_OF_BILLING_PERIOD',
            },
        },
    },
},

Custom attributes

When configuring the cancel flow, you can define custom attributes to effectively segment your customers:

1. Create the attribute

   Within the Configuration Settings tab, or directly from the cancellation flow in the Audience page, create a custom attribute.

2. Use it in a flow

   Apply flows for the specified segments within your cancel flow. For example, target customers who used a free trial and have already extended it.

3. Pass it at launch

   When invoking window.churnSolution.run(), include Has_Extended_Free_Trial under options.customerAttributes.

document.getElementById('cancel-button').addEventListener('click', function () {
    window.churnSolution?.run({
        authKey, // hash generated by your server
        subscriptionId, // your subscription ID from your payment provider
        appId: 'APP_ID', // your App ID
        options: {
            customerAttributes: {
                Has_Extended_Free_Trial: false // or true, based on user's status
            },
            record: true,
            email: '',
        },
    });
});

Video walkthrough: Custom attributes and segmentation on YouTube.

Customer segmentation based on metadata

Suppose you already have a metadata field, either in the customer metadata or the subscription metadata, and it's set for all your customers.

In the Configuration Settings tab, or directly from the cancellation flow in the Audience page, establish a new custom attribute. Specify the fields used in your metadata and their respective data types. Employ this custom attribute to define segments within your cancel flow, similar to the previous example.

Now, when a customer interacts with the embed, Churn Solution first prioritises the value of the entered key field, if provided during session creation. Then it searches for the relevant data in both their customer and subscription metadata. If found, it uses the value from the subscription metadata first, then from the customer metadata, to evaluate your segment conditions.

Three more entry points beside run().

Subscription renewal configuration

This feature allows you to win back customers who have cancelled their subscription with a cancellation setting of "at the end of the billing period" (the cancellation has not happened yet). Configure and display a call-to-action (CTA) to let your customers renew their subscription using these settings on the configuration page:

• Immediate renewal: once the user clicks the renew CTA, their cancellation is reverted directly.
• Renew with customer confirmation: set a headline, message and CTA text for the pop-up shown when the user clicks the renew CTA.
• Renew with special offer: add a headline, message, CTA text, and offer users a coupon that is applied to their first payment.

Once you've chosen the configuration, implement the renewal on your site. Typically you attach an event listener to your Renew Plan button. The following code calls a function on the Churn Solution side that handles the renewal:

document.getElementById('renew-button').addEventListener('click', function () {
    window.churnSolution?.renew({
        authKey, // hash generated by your server
        subscriptionId, // your subscription ID from your payment provider
        appId: 'APP_ID', // your App ID
        options: {
            record: true,
            email: '',
        },
    });
});

To replace the success message, pass cancellationSettings.uncancel_message. renew() reads cancellationSettings only for the success message, on the client. Nothing in it is sent to Churn Solution.

Resume configuration

This feature enables you to offer your customers the option to resume their subscription after they have paused payment collection. Configure and display a CTA to let your customers resume using these settings on the configuration page:

• Immediate resume: once the user clicks the resume CTA, their subscription is resumed directly.
• Resume with customer confirmation: set a headline, message and CTA text for the pop-up shown when the user clicks the resume CTA.

Attach an event listener to your Resume Plan button. The following code calls a function on the Churn Solution side that handles the resume process:

document.getElementById('resume-button').addEventListener('click', function () {
    window.churnSolution?.resume({
        authKey, // hash generated by your server
        subscriptionId, // your subscription ID from your payment provider
        appId: 'APP_ID', // your App ID
        options: {
            record: true,
            email: '',
        },
    });
});

To replace the success message, pass cancellationSettings.unpause_message. resume() reads cancellationSettings only for the success message, on the client. Nothing in it is sent to Churn Solution.

Pause flow

Launches the pause flow directly instead of the cancel flow. Available for WooCommerce and Paddle.

document.getElementById('pause-button').addEventListener('click', function () {
    window.churnSolution?.pause({
        authKey, // hash generated by your server
        subscriptionId, // your subscription ID from your payment provider
        appId: 'APP_ID', // your App ID
        options: {
            record: true,
            email: '',
        },
    });
});

To pause for one month immediately without showing a flow, call window.churnSolution?.skip({...}) with the same arguments.

Run your own billing code when a customer accepts an offer or cancels, instead of letting Churn Solution act in your gateway.

The model

Every action has a pair: a handleX callback and an autoX flag.

The handlers object

This object contains the action handlers with a flag for each action to specify whether the handler is a replacement for the Churn Solution handler or extra functionality. If any of the auto props is true, its action is handled from the Churn Solution side, and your callback for that event is also called when the action executes. You can also send the email of the customer who started the cancellation flow.

{
    record: true, // default true, switch to false to turn off recording
    email: '', // User email that initiates the cancel flow
    handleCancel: (customer, cancelFlowInfo) => {
        // cancel callback
    },
    handleAbandon: (customer, cancelFlowInfo) => {
        // abandon callback
    },
    handleDone: (customer, cancelFlowInfo) => {
        // success screen closed callback
    },
    handleClose: (customer, cancelFlowInfo) => {
        // modal closed callback
    },
    handlePause: ({pausePeriod}, customer, cancelFlowInfo) => {
        // pause callback
    },
    handleTrialExtension: ({trialExtensionDays}, customer, cancelFlowInfo) => {
        // trial extension callback
    },
    handleCoupon: ({code}, customer, cancelFlowInfo) => {
        // coupon/discount callback
    },
    handleSwitchPlan: ({plan}, customer, cancelFlowInfo) => {
        // switch plan callback
    },
    handleSwitchPlanWithCoupon: ({plan, code}, customer, cancelFlowInfo) => {
        // switch plan with coupon callback
    },
    // If any of the below props is true
    // its action will be handled from Churn Solution side
    autoCancel: false,
    autoPause: false,
    autoSwitchPlan: false,
    autoSwitchPlanWithCoupon: false,
    autoTrialExtension: false,
    autoCoupon: false,
}

Signatures

Offer handlers are called as handler(offer, customer, cancelFlowInfo), where offer carries offerType plus the fields below. handleCancel and the lifecycle callbacks receive (customer, cancelFlowInfo).

Return a Promise. resolve({ title, message }) replaces the success-screen text; reject({ message }) shows an error and keeps the subscription unchanged.

Example: custom cancel and pause

window.churnSolution?.run({
  authKey, subscriptionId, appId: 'APP_ID',
  options: {
    handleCancel: (customer, flowInfo) => new Promise(async (resolve, reject) => {
      try {
        await fetch('/api/billing/cancel', { method: 'POST', body: JSON.stringify({ subscriptionId }) });
        resolve({ message: 'Your account has been cancelled. You will not be billed again.' });
      } catch (e) {
        reject({ message: 'We could not cancel your account. Please contact support.' });
      }
    }),
    handlePause: ({ pausePeriod }, customer, flowInfo) => new Promise(async (resolve, reject) => {
      try {
        await fetch('/api/billing/pause', { method: 'POST', body: JSON.stringify({ subscriptionId, months: pausePeriod }) });
        resolve({ message: `Paused for ${pausePeriod} month${pausePeriod === 1 ? '' : 's'}. You will not be billed until you resume.` });
      } catch (e) {
        reject({ message: 'We could not pause your account. Please contact support.' });
      }
    }),
    autoCancel: false,
    autoPause: false,
  },
});

Lifecycle callbacks

Override any default string in the cancellation, resume or renewal flows, or force a language.

Force a language

options: { language: 'de' }

Custom texts

Pass customTexts as a map of original text → replacement. Only the keys you include change.

window.churnSolution?.run({
  authKey, subscriptionId, appId: 'APP_ID',
  options: {
    customTexts: {
      'Back': 'Retour',
      'Next': 'Suivant',
      'Decline Offer': "Refuser l'offre",
      'Accept Offer': "Accepter l'offre",
      'Done': 'Terminé',
      'Pause Subscription': "Mettre l'abonnement en pause",
      'Cancel Subscription': "Annuler l'abonnement",
      'Extend Free Trial': "Prolonger l'essai gratuit",
      'Claim your offer': 'Réclamez votre offre',
      'Switch Plan': 'Changer de forfait',
      'No, Back': 'Non, retour',
      'Yes, Leave': 'Oui, quitter',
      'Chat on WhatsApp': 'Discuter sur WhatsApp',
      'Send an Email': 'Envoyer un e-mail',
    },
  },
});

All overridable keys

"Back", "Next", "Decline Offer", "Done", "Cancel", "Cancel Subscription", "Close", "Yes, Leave", "No, Back",
"Powered by", "Cancellation Guaranteed by", "Offer Guaranteed by",
"You are already paused", "You won't be billed until your subscription resumes",
"Subscription Cancelled.", "Subscription Uncancelled.", "Subscription Resumed.", "Subscription paused.", "Subscription Activated.",
"You can enjoy all our features again!", "Something went wrong!", "Please refresh your page and try again",
"Offer applied", "Successfully claimed offer", "Switch Plan", "Successfully switched plan",
"Successfully switched plan with a discount.", "Extend Free Trial", "Successfully extended your free trial",
"Unable to Recover Payment", "Unable to Switch Plan", "Please contact customer support for assistance",
"Submit the form to proceed with your cancellation", "Go To Form", "Write your answer...", "Answer...", "empty option",
"Minimum number of characters:", "Day", "Days", "day", "days", "week", "weeks", "month", "months", "year", "years",
"billing cycle", "billing cycles", "Choose offer type", "Pause Subscription", "Accept", "Accept Offer", "Claim your offer",
"Switch and Claim Your Offer", "Discover a Better Plan for You", "Claim Your Offer & Switch Plan", "Extend Trial By",
"Chat on WhatsApp", "Send an Email", "Choose how long you want to pause", "Loading...", "Waiting Submit...",
"Limited time offer for", "Enjoy This Discounted Price Forever", "Your subscription is successfully restored",
"Your subscription is successfully resumed", "You won't be billed again.",
"Your subscription is canceled and will end at the end of your current billing period.",
"Your subscription is canceled and will end after", "Your subscription is canceled and will end", "Today", "Can't Cancel",
"Success", "Your action has been successfully done", "Cancellation Incomplete",
"You've started the cancellation process but haven't finished it. Are you sure you want to leave?",
"Oops! something went wrong!", "It seems you have already claimed this coupon", "Offer Already Redeemed",
"Off your next renewal", "Off all of your next renewals", "Off for"

Custom fonts

By default the flow uses the font chosen on the Design page. Override it per session:

options: {
  font: 'Roboto',
  fontUrl: 'https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&display=swap',
}

Ask customers to fill a Google Form before (or after) they confirm a cancellation. Optional or required.

Enable the form

1. Make the form public

   Anyone with the link must be able to answer.

2. Turn it on in the confirmation step

   In the flow's cancellation confirmation settings, enable the Google Form button, set its text and the form URL.

3. Optional: require submission

   Enable "require Google Form submission" to block cancellation until the form is submitted. This needs the validation setup below.

Required-submission setup

1. Add a "Cancellation Bin Code" field

   A Short answer question titled exactly Cancellation Bin Code. It is pre-filled with a unique value at runtime. Important: inform customers not to edit this field, as the unique value is essential for form validation.

   

2. Open the Script editor

   In the Google Form builder, click the three dots in the upper right corner and select Script editor. Paste the script below and save.

   

   

3. Add a trigger

   From the same page, click Triggers → Add trigger and match these settings: function onFormSubmit, event source From form, event type On form submit. Save the trigger so it appears on the triggers page.

   

   

4. Set the confirmation message

   In the form settings go to Settings → Presentation → After submission → Confirmation message and tell customers not to close the form, for example: "Your response has been recorded! Please keep this form open until we process your cancellation. We'll close it automatically when done. Thank you!"

   

function onFormSubmit(e) {
  const CANCELLATION_BIN_CODE_FIELD = "Cancellation Bin Code";
  const API_URL = 'https://google-form.churnsolution.com/submit';

  const itemResponses = e.response.getItemResponses();
  const cancellationBinCode = itemResponses
    .find(item => item.getItem().getTitle() === CANCELLATION_BIN_CODE_FIELD)
    ?.getResponse();

  if (!cancellationBinCode) {
    Logger.log('Error: Cancellation Bin Code is empty. Aborting API call.');
    return;
  }
  try {
    UrlFetchApp.fetch(API_URL, {
      method: 'post',
      contentType: 'application/json',
      payload: JSON.stringify({ cancellationBinCode }),
    });
  } catch (error) {
    Logger.log('Error during API request: ' + error.message);
  }
}