NAV Navbar
  • Introduction
  • Getting Started
  • Form Settings
  • Option Settings
  • Configuring Actions
  • Customize Views
  • Testing Environment
  • Handling Webhooks
  • Insights & Analytics
  • Introduction

    Welcome to the BurnChurn documentation! This documentation will help walk you through the simple process of configuring the BurnChurn form on your site to begin recovering users, tracking exit feedback, and automating processes.

    If you have any trouble or questions regarding this documentation or BurnChurn, feel free to contact us at any point.

    We are working to add pictures to enhance understanding of the documentation in the near future.

    Getting Started

    Connecting Stripe

    In order to take full advantage of the functionality that BurnChurn offers to automate processes for your users, we integrate heavily with Stripe to manage your users, subscriptions, and payments.

    Authenticating your Stripe account with BurnChurn is a one-time, one-step process that happens on registration in order to integrate with your application. If you don't have a Stripe account, you can sign up for one here.

    Installing the Form

    Once you've registered your account and authenticated with Stripe, you'll be redirected to the form editor where you'll notice that your form is already pre-populated with suggested options for you to configure, create, or delete.

    <!-- Insert this code where you would like your form to be -->
    <script id="churn-script" src="https://burnchurn.io/embed.js" api-key="9PMFR6NV9GY8XBMOLDLYW440FNNG301M" 
    stripe-customer-id="RENDER_CUSTOMER_ID_HERE"></script>
    <div id="churn-form"></div>
    

    By default, BurnChurn is in "Live" and working mode, so integrating is as easy as grabbing the generated embed code at the bottom of the form editor page and replacing your delete button with the new embed code. It should look something like the following:

    Now, you're free to configure, test, and automate away! Any further changes made to the form on BurnChurn will automatically update.

    Configuring Settings

    BurnChurn offers a number of different functionalities - from notifying you if a user is considering quitting, pausing a subscription, issuing webhooks, extending or changing the plan a user is considering automatically, and more.

    In order to take advantage of these features, sign in, and navigate to the Form Editor to customize your form options and actions. There is more information below regarding how to setup your form for more advanced functionality.

    Form Settings

    Text Options

    At the top of the form editor page, you'll notice options for editing your form settings. The "Header Main", "Header Subtitle", and "Button Main" alter the text that is shown at the top of the form if you are using a button/modal embed type, as well as the corresponding button text to view the form.

    The theme color and other button-specific CSS can be added here. Note that some of these settings may only apply if you are using the embed in "Button" mode versus "Direct Embed".

    Embed Type

    The BurnChurn form can be embedded either directly into the page or as a button/modal. By default, the button/modal type is enabled.

    This can be toggled, and the result shows in the righthand preview. The difference is simply whether you prefer to embed options directly into the page, or use a button to launch the modal. In both cases, users will stay on the same page of your application in which you've embedded it.

    Custom Styling

    While the theme color and button CSS can be individually managed, we provide the option to fully customize the style of your form to integrate more closely with your own application through the "Custom CSS" field near the bottom of the page.

    Selectors, like those below, are available and pre-written to make it easy to change the style as you wish. Similar to the rest of the form, these changes happen as they are saved in real-time to your already existing form.

      /* label holder for each option added */
      label.option {}
    
      /* radio input */
      input[type=radio] {}
    
      /* Reason to Delete */
      .main-text {}
    
      /* holder div that opens when radio input is selected */
      .extra-info {}
    
      /* User Instructions */
      .extra-heading  {}
    
      /* Additional Feedback Input */
      .rescue-choices > input[type=text] {}
    
      /* button to submit */
      .option-submit {}
    

    Setting Defaults

    The "Default Redirect URL" allows you to check the option that a user is redirected, and when a custom URL is not supplied, this URL is used.

    The "Webhook URL" is the endpoint which we will send webhooks to. Again, you can set a custom webhook endpoint for specific actions, but this will be used as default if you add webhooks.

    Your API key is automatically set and unchangeable. This is used to identify your form in requests and should be included (by default) in your embed code.

    It is highly recommended to add these default settings as soon as you might know them.

    Option Settings

    Text Options

    You can collapse, drag and drop to reorder, delete, and edit options that are contained within the form. Notably, the "Reason to Delete", "User Instructions", "Button Text", "Additional Information Heading", and "Additional Information Details" fields all allow for you to specify and change text for the option to show to a user.

    When you edit, reorder, delete, or otherwise interact with these elements on the lefthand side of the page, you should see an updated preview of the changes on the righthand side, and a "Form Saved" notification.

    Collecting Text Feedback

    By enabling the option "Collect Text Feedback?", you can get even more detail into why your users might be leaving and track their exit feedback.

    This option enables a form for users to fill out when they choose an option, potentially answering a question like "Why have you decided to pause your subscription?", "What other apps have you found better?", "How can we improved user experience?", and more which you can tailor to get the answers you need to decrease churn.

    Managing User Types

    The ability to show an option to a specific user type/persona is currently in development.

    On completion of this feature, you will have the option to configure whether you want a user to be allowed to: - View only if they have not already selected the option previously - View only if they are on a certain plan - View only if they are trialling (or not) - View only if they are on a paused account - and more.

    Option Actions

    A large portion of the power behind using BurnChurn is its ability to automate actions which can save your users through integration with your application, Stripe, notifications, and more. Read on to learn more about which actions are supported and how to use them.

    Configuring Actions

    Stripe

    Stripe actions allow you to automate the process of most steps regarding the management of your users' accounts.

    Simply check the box to enable a stripe action, then select the corresponding action you want to happen for the user.

    You can offer discounts, trial extensions, pausing billing, and more to keep users happy and give you time to make sure they do not churn.

    Add a Coupon

    Choose "Add a Coupon" on the Stripe dropdown. Depending on the environment you are in, "Live" or "Test", the corresponding coupons will be loaded for that option.

    Once you've selected one, if a user chooses this option, that coupon will be applied to their account.

    Extend Trial

    Choose "Extend Trial" on the Stripe dropdown. Specify the number of days that you would like the user's trial to be extended by.

    Pause Billing

    Choose "Pause Billing for X Months (starting immediately)" or "Pause Billing for X Months (at end of period)" based on your preference. Then indicate the number of months for which you would like the option to pause an account's billing. Pausing an account does have proration enabled by default.

    There are a variety of ways that one can handle pausing an account with Stripe. We've chosen to implement pausing a subscription by canceling the subscription, either immediately or at period end depending on your selection, and scheduling the Stripe customer to subscribe back to the plan in the number of months specified.

    We then issue a webhook to your application if a webhook URL is specified for the option when the account is unpaused.

    Note that the following additions are in development - Stripe User notifications that their subscription is beginning again - Showing the option to "Immediately Unpause" for users that are on a paused account.

    Cancel Subscription

    You can choose to "Cancel Subscription (Immediately)" or to "Cancel Subscription (at period end)".

    Switch to Different Plan

    You can choose to allow users to switch to a different plan. Like Adding Coupons, we automatically import your Stripe plans for the environment you are currently using.

    Switching plans does have proration on by default.

    Redirects

    You can also set your form to redirect the user after they have submitted their option.

    You can specify a custom URL to redirect to for a single option, or leave the URL empty in order to have the option redirect to the form's default redirect URL.

    Notifications

    You can get notified each time a user performs or chooses a specific option on your form.

    This allows you to know which users are considering quitting and respond according to their feedback or choice.

    You can also configure this as a way to "contact support" in case they are interested in quitting because they don't understand the product or have a similar need.

    Webhooks

    Notify your application of a user's action using webhooks. Choose to set a custom webhook for that action, or it will automatically send webhooks to the default URL if you indicate to do so.

    This way you can perform custom logic based on the choices your users make. The webhooks contain parameters to interact with your application, select "Handling Webhooks" in order to learn how to receive and handle webhooks with your application.

    You can specify a custom webhook URL for a single option, or leave the webhook URL empty in order to use the form's default webhook URL.

    Customize Views

    Often times you may only want a user to be able to execute an option one time, on a certain plan, if they are trialling, or if they are paused, or a number of other options and combinations.

    This can be useful if you want to allow a user to extend their trial or add a coupon one time, only show the option to downgrade for users on your top-tier plan, and more.

    BurnChurn makes it easy to do this by including the "Cusomize User View" on a per-option basis.

    Show to Plans Except

    This setting automatically imports the plans in the environment you are currently toggled into. By default it is "Not Set" and your option will be shown to all users.

    Selecting a plan for this setting will show the option only to users who are not on the plan that you have selected. Note that behavior can vary when used in combination with "Show Only to Plan".

    Show Only to Plan

    This setting automatically imports the plans in the environment you are currently toggled into. By default it is "Not Set" and your option will be shown to all users.

    Selecting a plan for this setting will show the option only to users who are on the plan that you have selected, and no others. Note that behavior can vary when used in combination with "Show Only to Plan".

    Show Option Multiple Times

    This option allows your users to select the option more than once. For example, if the option is "I need help from support", then you may want a user to be able to select the option in the future. However, if a user is extending their trial, you may only want them to be able to do this once.

    By default this is set to true.

    Show to Paused Users

    This option has two settings "Only" and "Except". The former, if enabled, will only show the option to users who have previously paused their account using BurnChurn. The latter, if enabled, will only show the option to users who are not currently on a paused account using BurnChurn.

    Note that if both of these settings are checked, or not checked, the option will show to users regardless of whether they are paused.

    Show to Trial Users

    This option has two settings "Only" and "Except". The former, if enabled, will only show the option to users who are currently on a Stripe trial. The latter, if enabled, will only show the option to users who are not currently on a Stripe trial.

    Note that if both of these settings are checked, or not checked, the option will show to users regardless of whether they are on a trial.

    Testing Environment

    You can enable or disable the testing environment by toggling the option in the navigation sidebar and reloading the page.

    Error Reporting

    Enabling this option will display "Test Mode" in red on your form, and changes will only affect customers, plans, coupons, and other objects in your Stripe Test environment.

    Be certain when you switch modes that the Stripe customer ID's, plans, and coupons that you have configured match the environment into which you've toggled.

    Plans & Coupons

    By default, the plans and coupons which are shown for selection in certain options' configuration as well as the Stripe calls made will use the Stripe environment in which you've decided to enable. Responses that are made in each mode will only be viewable in that mode.

    Handling Webhooks

    Custom Logic

    While BurnChurn provides the ability to automate all of these actions for you, it can be useful to notify your application when a change is being made in order to implement custom logic such as blocking access to a user, showing different content, and more.

    For this purpose, BurnChurn can send webhook events that notify your application any time an event happens on your account. This is especially useful for events—like disputed charges and many recurring billing events—that are not triggered by a direct API request. This mechanism is also useful for services that are not directly responsible for making an API request, but still need to know the response from that request.

    You can register webhook URLs that we will notify any time an event or option selection happens in your account. When the event occurs, we handle the actions based on your settings, and issue a notification to your endpoint with the information in case you would like to implement custom logic based on actions such as restricting or enabling access, limiting requests, and more.

    When to Use

    Webhooks are necessary only for behind-the-scenes transactions and custom logic for your application. Most BurnChurn requests generate results and perform actions which don't require webhooks for verification. Also, because of BurnChurn's tight integration with Stripe, it may make more sense for your application to query the Stripe API versus implementing webhooks.

    If you use BurnChurn only to collect and track exit feedback, or intervene with customer support, implementing webhooks will not be necessary.

    Configuration

    Webhooks can be configured by navigating to the form editor page, and setting your default webhook URL. Once this is filled, checking the Action to "Send Webhook" will automatically issue a webhook to either the custom URL that is specified for the option, or, as a backup, to the default URL provided.

    Webhooks are currently issued from BurnChurn in two cases: when a user selects an option or when a user's account becomes active again (unpauses their subscription).

    Webhooks will be issued regardless of whether your application is in Test or Live mode, but will contain a parameter indicating the current environment, so be sure to interpret the requests accordingly.

    Receiving Webhooks

    Creating a webhook endpoint on your server is no different from creating any page on your website. With PHP, you might create a new .php file on your server; with a framework like Sinatra, you would add a new route with the desired URL.

    Webhook data is sent as JSON in the POST request body. The full details are included and can be used directly, after parsing the JSON.

    The following examples are borrowed from the Stripe documentation, but are just as applicable to our own endpoints.

    Ruby:

    require 'json'
    
    # Using Sinatra
    post '/my/webhook/url' do
        # Retrieve the request's body and parse it as JSON:
        event_json = JSON.parse(request.body.read)
    
        # Do something with event_json
    
        status 200
    end
    

    Python:

    import json
    from django.http import HttpResponse
    
    # Using Django
    def my_webhook_view(request):
      # Retrieve the request's body and parse it as JSON:
      event_json = json.loads(request.body)
    
      # Do something with event_json
    
      return HttpResponse(status=200)
    

    PHP:

    // Retrieve the request's body and parse it as JSON:
    $input = @file_get_contents('php://input');
    $event_json = json_decode($input);
    
    // Do something with $event_json
    
    http_response_code(200); // PHP 5.4 or greater
    

    Java:

    // Using the Spark framework (http://sparkjava.com)
    public Object handle(Request request, Response response) {
      // Retrieve the request's body and parse it as JSON:
      Event eventJson = APIResource.GSON.fromJson(request.body(), Event.class);
    
      // Do something with eventJson
    
      response.status(200);
      return "";
    }
    

    Node:

    // This example uses Express to receive webhooks
    const app = require('express')();
    
    // Retrieve the raw body as a buffer and match all content types:
    app.use(require('body-parser').raw({type: '*/*'}));
    
    app.post('/my/webhook/url', function(request, response) {
      // Retrieve the request's body and parse it as JSON:
      const event_json = JSON.parse(request.body);
    
      // Do something with event_json
    
      response.send(200);
    });
    

    .NET

    using System;
    using System.IO;
    using Microsoft.AspNetCore.Mvc;
    using Stripe;
    
    namespace workspace.Controllers {
        [Route("api/[controller]")]
        public class StripeWebHook : Controller {
            [HttpPost]
            public void Index() {
                var json = new StreamReader(HttpContext.Request.Body).ReadToEnd();
                var stripeEvent = StripeEventUtility.ParseEvent(json);
    
                // Do something with stripeEvent
            }
        }
    }
    

    Note that if you are using Rails, Django, or another web framework, you may need to exempt your webhooks route from CSRF protection. These frameworks do automatic checks to make sure that every POST request contains a CSRF token in order to protect you and your users from cross-site request forgery attempts. However, it can also prevent the receipt of legitimate webhooks. A few examples can be seen below.

    Rails:

    class StripeController < ApplicationController
        # If your controller accepts requests other than Stripe webhooks,
        # you'll probably want to use `protect_from_forgery` to add CSRF
        # protection for your application. But don't forget to exempt
        # your webhook route!
        protect_from_forgery :except => :webhook
    
        def webhook
            # Process webhook data in `params`
        end
    end
    

    Django:

    import json
    
    # Webhooks are always sent as HTTP POST requests, so ensure
    # that only POST requests reach your webhook view by
    # decorating `webhook()` with `require_POST`.
    #
    # To ensure that the webhook view can receive webhooks,
    # also decorate `webhook()` with `csrf_exempt`.
    @require_POST
    @csrf_exempt
    def webhook(request):
      # Process webhook data in `request.body`
    

    Responding to Webhooks

    To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. All response codes outside this range, including 3xx codes, will indicate to us that you did not receive the webhook. This does mean that a URL redirection or a "Not Modified" response will be treated as a failure. BurnChurn will ignore any other information returned in the request headers or request body.

    Example Webhook

    Here is an example of a webhook that may be issued by BurnChurn to your application so that you can understand how to parse the JSON object successfully.

    {
      stripe_customer: "cus_12345678",
      option_selected: "I need more time to trial the product.",
      feedback_included: true,
      feedback: "5 days was not a long enough trial for me to try the product."
      actions: [
        stripe: {
          type: "Extend Trial",
          setting: "5"
        },
        redirect: {
          type: "option",
          url: "https://site.com/getting-started"
        }
        notification: {
          type: "option",
          email: "[email protected]"
        },
        webhook: {
          type: "form",
          url: "https://site.com/webhook"
        },
      ]
    }
    

    Let's look at what is happening above. First, the stripe_customer ID that was passed to BurnChurn on option select is included in the webhook so that you can find the user in your own application and identify the user by this ID. Then, the option that was selected is included as the "option_selected" element.

    If you have collecting text feedback enabled, then "feedback_included" will be true, and the field "feedback" will include the feedback that the user has provided.

    Any actions that you have enabled for the option, whether a Stripe action, redirect, notification, webhook, or other action, will be included in the "actions" field.

    For "stripe", the "type" field will indicate the Stripe action that took place and includes: - Add a Coupon - Extend Trial - Pause Billing - Cancel Subscription - Downgrade to Different Plan

    and the "setting" field will be included for those actions which require further configuration such as adding a coupon, which will have the coupon name, extending a trial, which has the number of days, pause billing, which will have the number of months, and downgrading your plan, which has the name of the plan to downgrade to.

    The other 3 actions, "redirect", "notification", and "webhook", will have a type, which tells you whether it used the form default (URL or email) or the custom option setting, indicated by "option" or "form". This will default to the "option" type if it is set, and fall back to the "form" type. Then "url" and "email" will have the information accordingly.

    The webhook that is issued when a user's account is unpaused looks like the following:

    {
      stripe_customer: "cus_12345678",
      actions: [
        stripe: {
          type: "Resume Subscription",
          setting: "Plan Name"
        }
      ]
    

    Insights & Analytics

    Overall Statistics

    At the top of the Insights page, you'll notice four core statistics: - the number of cancels you've had - the "Save" success percentage of the BurnChurn form - the churn rate - the revenue recovered

    By default this information is shown for the past week. In order to view a different date range, simply use the date selector to configure it to your specification.

    User Interactions

    User responses are tracked and categorized as either a "Save", "Pause", or "Delete". By utiling the graph chart and table array that we provide, as well as configuring the date as necessary, you can view which users have chosen which options, as well as other statistics such as which plan they were on, the feedback they left, when the option was chosen, and more.

    Result Distribution

    We also show a distribution of the options that are chosen by your users in order for you to determine what is working to reduce churn and the most common feedback that users are providing you.