3 Simple Steps to Get Started

How to integrate the cancellation flow with your application or service:

Step 1 : Insert the Churn Solution JS Embed Code

The following code will add the Churn Solution client-side script and make itself available in the global JS namespace as window.churnsolution. You can use it to start the off boarding process for your customers. Just add it to the <body> section of your HTML.


<script>
    !function(){
        if (!window.churnsolution || !window.churnsolution.ready) {
            window.churnsolution = { ready: true };
            const s = document.createElement('script');
            s.src = 'https://app.churnsolution.com/sdk/index.min.js';
            s.async = true;
            const e = document.getElementsByTagName('script')[0];
            e.parentNode.insertBefore(s, e);
        }
    }();
</script>

Or you add it to the <head> section of your HTML as:


<script src="https://app.churnsolution.com/sdk/index.min.js"></script>

Step 2: Server-side authentication

Server-side authentication is implemented to ensure that all requests sent by Churn Solution to your payment provider on your behalf are valid and authorized. You can do it by generating an HMAC hash (SHA256 algorithm) with the API_KEY and your STRIPE_SUBSCRIPTION_ID key.

You can find your API_KEY in Account setting page.

Replace "STRIPE_SUBSCRIPTION_ID" with your actual Stripe subscription ID.

Before starting the Churn Solution flow, you should send a request to your server. This request will validate its permission usually through existing authorization measures for user actions. The hash generated by this code should be sent to front end to be used in the next step.

Below are some examples of how this hash can be generated in different backend languages.


private static String getSha256HmacHash(String API_KEY, String STRIPE_SUBSCRIPTION_ID) throws NoSuchAlgorithmException, InvalidKeyException {
    Mac sha256HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
    sha256HMAC.init(secretKeySpec);

    byte[] hash = (sha256HMAC.doFinal(STRIPE_SUBSCRIPTION_ID.getBytes()));
    StringBuffer result = new StringBuffer();
    for (byte b : hash) {
       result.append(String.format("%02x", b));
    }
    return result.toString();
}

Step 3: Link your cancel button to Churn Solution flows:

Once you've created an HMAC hash and sent it to your website's front end, you can set up Churn Solution and decide how you want it to appear. Typically, you will attach an event listener to you’re "cancel" button.

Adding the authHash is simple, follow the instructions in the Server Side Authentication section above to create an HMAC hash and pass it to the authkey parameter. The below code calls a function in Churn Solution side that accepts the authkey generated by the back end, the customer's stripe id and the company App Id.


document.getElementById('cancel-button').addEventListener('click', function () {
    window.churnSolution?.run(
    authKey, // hash generated by the back end
    customerStripeId, // customer's stripe subscription id
    'APP_ID', // your App Id
    {
        // options
        "cancellationSettings": {
            "settings": {
                "CANCEL_TIME": {
                    "cancellation_time_type": "CUSTOM_DATE", // can be: "END_OF_BILLING_PERIOD", "IMMEDIATE"
                    "cancel_after_days": 0
                }
            }
        }
        record: true,
        email: '',
    }
)});

You can find your APP_ID in Network setting page, after successfully linking your account with Stripe.

Configuration Options

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 Step 3: Link your cancel button to Churn Solution flows from the installing section.

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 will be terminated immediately upon cancelling his subscription.
EndOfBillingPeriod: Select this option to handle cancellations at the end of the current billing period. This allows customers to access services until the end of their paid subscription duration.
Custom: Opt for this option for personalized cancellation processes. If chosen, specify a Cancellation Delay in terms of the number of days to define the precise termination timeline.

Please Note: While each flow typically follow the configuration page settings, you have the flexibility to override this default behavior for any customer. Simply set the Cancellation Term option to either "Immediate," "EndOfBillingPeriod," or "Custom" in Step 3: Link your cancel button to Churn Solution flows from the installation section.

Custom Attributes

When configuring the cancel flow, you can define custom attributes to effectively segment your customers. Here's how to proceed:

Within the Configuration Settings tab or directly from the cancellation flow in the Audience page, create a custom attribute. For instance, you might create an attribute like Has_Extended_Free_Trial to segment users based on whether they've already extended their free trial.
Use this custom attribute to apply flows for the specified segments within your cancel flow. For example, you could target customers who have use free trial and have already extended it.
When invoking window.churnSolution.run(), ensure that you include Has_Extended_Free_Trial under customerAttributes.


document.getElementById('cancel-button').addEventListener('click', function () {
    window.churnSolution?.run(
    authKey, // hash generated by the back end
    customerStripeId, // customer's stripe subscription id
    'APP_ID', // your App Id
    {
        // options
        customerAttributes: {
            Has_Extended_Free_Trial: false // or true, based on user's status
        },
        record: true,
        email: '',
    }
)});

Customer Segmentation based on Metadata

Suppose you already have a metadata field either from the customer metadata or 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, we'll first prioritize the value of the entered key field, if provided during session creation. Subsequently, we'll search for the relevant data in both their customer and subscription metadata. If found, we'll use that value from the subscription metadata first, then from the customer metadata, to evaluate your segment conditions.

Custom Callbacks

Handler callbacks are used when you want to manage actions to a customer's subscription by yourself, rather than letting Churn Solution do it automatically for you. When you define a handler callback for a specific event, like a subscription cancellation, Churn Solution will follow your instructions instead of doing its implementation for it.

Most of these handler callbacks work like promises in JavaScript. When something happens, you have two options: resolve or reject. If everything goes well and you want Churn Solution to proceed as planned, you call resolve. You can even include a message to let the customer know what's happening. On the other hand, if there's an issue and you want Churn Solution to stop and handle it differently, you call reject.

This object will contain the actions handlers with a flag for each action to specify whether the action handler is a replacement to Churn Solution handler or an extra functionality. If any of the below props is true its action will be handled from Churn Solution side and if you have callback for this event it will be called also when executing the action events from our side. Furthermore, you have the option to send the customer email 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) => {
        // cancel callback
    }, handleAbandon: (customer) => {
        // close callback
    }, handlePause: ({pausePeriod}, customer) => {
        // pause callback
    }, handleTrialExtension: ({trialExtensionDays}, customer) => {
        // trial extension callback
    }, handleCoupon: ({code}, customer) => {
        // coupon/discount callback
    },
    // If any of the below props is true
    // its action will be handled from Churn Solution side
    autoCancel: false,
    autoPause: false,
    autoSwitchPlan: false,
    autoTrialExtension: false,
    autoCoupon: false
}

Example callbacks for custom cancel handling

If you want to customize and use your cancel logic rather than using Stripes Cancelling Mechanism, you can define handleCancel option and set the autoCancel to false, similarly you can do it to all other actions. This callback is triggered when a customer selects to cancel his subscription. If you've defined this callback, Churn Solution won't automatically attempt to manage this actions through Stripe. Instead, it will execute the logic you've specified within the respective callback.


window.churnSolution.run(
    'HASH', // hash generated by the back end
    'STRIPE__CUSTOMER_ID', // customer's stripe subscription id
    'APP_ID',
    {
        handleCancel: (customer) => {
            return new Promise(async (resolve, reject) => {
            try {
                // handle cancel logic

                // You can pass a message that will be showed to user after cancelling
                // if you don't pass a message, a generic message will be shown
                resolve({ message: 'Your account has been canceled. You will not be billed again' });
            } catch (e) {
                console.log(e);
                reject({ message: 'Failed to cancel account. Please contact support.' });
            }
        });
        }, handlePause: async ({pausePeriod}, customer) => {
            return new Promise(async (resolve, reject) => {
            try {
                // handle pause logic

                // You can pass a message that will be showed to user after cancelling
                // if you don't pass a message, a generic message will be shown
                resolve({ message: `Your account has been paused ${pausePeriod} month${pausePeriod === 1 ? '' : 's'}. You will not be billed until resume` });
            } catch (e) {
                console.log(e);
                reject({ message: 'Failed to cancel account. Please contact support.' });
            }
        });
        },
        // If any of the below props is true
        // its action will be handled from Churn Solution side
        autoCancel: false,
        autoPause: false,

)