Frontend Capabilities

# Churn Deflection ✨

Previous Version

The earlier version of Churn Deflection was delivered via Brightback.js, which has since been deprecated. You can still view the documentation (opens new window) for reference.

# Introduction

Churn Deflection (opens new window) helps retain customers by intercepting cancel flows and presenting alternative options like discounts, plan changes, or feedback forms. Using the Chargebee JavaScript SDK, you can trigger predefined deflection experiences that leverage customer context, subscription details, or any custom parameters. The SDK fetches the best-matched page, which is hosted by Chargebee. You can configure redirection behavior based on user decisions. This setup allows for dynamic intervention before subscription termination, without heavy client-side implementation.

# Integration guide

This guide helps you set up Churn Deflection into your application by integrating the Chargebee.js SDK.

# Prerequisites

Audit (opens new window) your churn deflection flows and set up (opens new window) deflection experiences in Chargebee.

# Integrate Chargebee.js SDK

# 1. Load Chargebee.js

Load Chargebee.js by adding the following script to the <head> element of the page that contains the cancel button for the subscription.

<script src="https://js.chargebee.com/v2/chargebee.js"></script>
1

# 2. Initialize Chargebee.js

Once the page loads, initialize Chargebee.js with your Chargebee site domain name to enable the use of the SDK.

const chargebee = window.Chargebee.init({
   site: "YOUR-CHARGEBEE-SUBDOMAIN",
})
1
2
3

# 3. Create the Churn Deflection object

Use the churnDeflection() function to instantiate Churn Deflection.

const churnDeflection = await chargebee.churnDeflection();
1

# 4. Choose your integration approach

You can now implement churn deflection in one of two ways:

  • Attach a cancellation handler: Add churn deflection with almost no code (replace an existing Cancel link).

  • Prefetch and redirect: Use this approach to run custom logic before redirecting (analytics, dialogs, feature flags) or trigger cancellation from multiple places.

# Option 1: Attach a cancellation handler

DETAILS
# 1. Set the id of the cancellation CTA to cb-cancel

Define a cancellation CTA in your application with the id set to cb-cancel. This must be a link that the user clicks to cancel their subscription.

⚠️ Required step
This is a required step for the integration to work.

<a id="cb-cancel" href="https://app.yourcompany.com/cancel" class="btn btn-danger">
  Cancel Subscription
</a>
1
2
3
# 2. Connect the churn deflection page URL to the cancellation CTA

Call the churnDeflection.attachCancelHandler() function as soon as the cancellation CTA is displayed to the user. This attaches a click handler to the cb-cancel CTA and initializes the churn deflection flow.

churnDeflection.attachCancelHandler({
  account: {
    customerId: "16CRibUdE6pV6HoU",
    firstPurchaseDate: "2024-06-26"
  },
  externalUserId: "jane_doe",
  firstName: "Jane",
  lastName: "Doe",
  saveReturnUrl: "https://app.yourcompany.com/save?id=jane_doe",
  cancelConfirmationUrl: "https://app.yourcompany.com/cancel_confirm?id=jane_doe",
  custom: {
    emailCount: 4208
  }
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Your application is now wired up to deflect cancellation attempts by the customer. On clicking the cancellation link, they will be immediately redirected to a personalized Churn Deflection page.

# Option 2: Prefetch a churn deflection page and redirect

DETAILS
# 1. Set the parameters for the churn deflection page
let options = {
  account: {
    customerId: "16CRibUdE6pV6HoU",
    firstPurchaseDate: "2024-06-26"
  },
  externalUserId: "jane_doe",
  firstName: "Jane",
  lastName: "Doe",
  saveReturnUrl: "https://app.yourcompany.com/save?id=jane_doe",
  cancelConfirmationUrl: "https://app.yourcompany.com/cancel_confirm?id=jane_doe",
  custom: {
    emailCount: 4208
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 2. Write a helper function to handle clicks on the cancellation CTA
function bindLink(id, url) {
    document.getElementById(id).addEventListener('click', () => {
        window.location.assign(url);
    });
}
1
2
3
4
5
# 3. Prefetch the churn deflection page and prepare for redirection

Call the churnDeflection.getPage() function to fetch the churn deflection page as soon as the cancellation CTA is displayed to the user. This reduces latency and ensures the churn deflection page loads promptly when the user decides to cancel.

Use the helper function defined above to bind the click event to the cancellation CTA. If the page is valid, redirect to the deflection page URL; otherwise, redirect to a fallback cancellation page.

churnDeflection
  .getPage(options)
  .then((result) => {
    if (result.valid) {
      // Do any additional processing here.
      bindLink('cancel-btn', result.url);
    } else {
      // Read and process result.errorMessage or redirect to cancellation page:
      bindLink(
        'cancel-btn',
        'https://app.yourcompany.com/cancel?id=jane_doe'
      );
    }
  });
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Your application is now wired up to deflect cancellation attempts by the customer. On clicking the cancellation CTA, they will be immediately redirected to a personalized Churn Deflection page.

# Best practices

# Local development

By default and for security reasons, Chargebee does not respond to churn deflection API requests from localhost. For local development to work, temporarily map a domain to your localhost to verify the XHR request or use a tunnel service like ngrok (opens new window) or localtunnel (opens new window). Watch the network tab in your DOM inspector to diagnose any additional issues.

# Render within iframes

You can embed the Chargebee Churn Deflection experience within your application using an iframe (opens new window). To do so securely, you must configure a vanity domain that matches the domain of your website. For example, if your app runs at https://app.yourcompany.com, the iframe must load from a domain like https://cancel.yourcompany.com. Domains like yourcompany.chargebee.com cannot be embedded in an iframe due to cross-origin restrictions.

# JS API reference

See the Churn Deflection JS API reference for more details.

← Functions →