Frontend Capabilities

# Retention ✨

Previous Version

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

# Introduction

Chargebee Retention (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 cancel 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 Chargebee Retention into your application by integrating the Chargebee.js SDK.

# Prerequisites

Audit (opens new window) your cancel page flows and set up (opens new window) cancel 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 Cancel Page object

Use the cancelPage() function to instantiate Cancel Page.

const cancelPage = await chargebee.cancelPage();
1

# 4. Choose your integration approach

You can now implement the cancel page in one of two ways:

  • Attach a cancellation handler: Add the cancel page 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 cancel page page URL to the cancellation CTA

Call the cancelPage.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 cancel page flow.

cancelPage.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 cancel page hosted by Chargebee.

# Option 2: Prefetch a cancel page and redirect

DETAILS
# 1. Set the parameters for the cancel 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 cancel page and prepare for redirection

Call the cancelPage.getPage() function to fetch the Chargebee cancel page as soon as the cancellation CTA is displayed to the user. This reduces latency and ensures the cancel 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 Chargebee cancel page URL; otherwise, redirect to a fallback cancellation page.

cancelPage
  .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 cancel page hosted by Chargebee.

# Best practices

# Local development

By default and for security reasons, Chargebee does not respond to cancel page 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 cancel page 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 Cancel Page JS API reference for more details.

← Functions →