Docs

Retention

Integrate Chargebee Retention via Chargebee.js

Previous Version

If you are using Brightback.js, the older version of the Chargebee Retention JS SDK, the installation steps can be found in the Appendix below.

Overview

Setting up Chargebee Retention into your site or app requires integrating Chargebee.js SDK on the page where your cancel button is located or making a precancel request. Then, configure how you will process cancels and offers.

Your admin can use the Chargebee Retention Experience Manager to design the cancel page experience, including retention strategies, branding, loss aversion, offers, and survey questions.

Chargebee Retention via Chargebee.js redirects your customer when they click the cancel button. It returns the URL of a customized cancel page to redirect your user while performing tasks like:

  • Pulling custom data about your canceling customer.
  • Using that data to personalize the cancel experience (e.g., dynamic offers, loss aversion carts, or alerts).
  • Segmenting your customer based on standard or custom data fields.

Steps to integrate Chargebee.js

Use Chargebee.js to integrate Chargebee Retention into your website or application. For step-by-step instructions, see the Chargebee.js documentation on integrating Chargebee Retention.

Appendix

Integrate Brightback.js (earlier version)

Installation Steps

Important Note

This section describes how to integrate Brightback.js, the earlier version of the Chargebee Retention JS SDK.

  • If you already use Chargebee Billing, we recommend using Chargebee.js for a unified and future-ready integration.
  • If you don't use Chargebee Billing yet, you can continue with Brightback.js without interruption. We'll provide a clear migration path to Chargebee.js and notify you when it's available.

Steps to set up Brightback.js

  1. Embed the Brightback.js snippet on the page where your customer clicks cancel (e.g., account settings/management).
  2. Add custom data fields to enrich customer records, create audiences, and personalize content in Chargebee Retention. See Chargebee Brightback suggested data fields.
  3. Link the code to your cancel or downgrade button.

Note:

Steps 1 and 3 are enough to get immediate benefits from Chargebee Retention. However, step 2 provides a richer, more personalized experience for your customers. Pro tip: Scroll to the bottom of this article for a "bare minimum" installation.

Email Chargebee Brightback.js installation instructions to your developer here.

Test Brightback.js locally

For security reasons, Chargebee Retention's server does not respond to a cancel initiation (precancel) request from localhost. To test from your local machine during development, temporarily map a domain to your localhost or use a tunnel service like ngrok or localtunnel. Use the network tab in your browser's developer tools to diagnose issues.

Example

127.0.0.1 localhost example.local

1. Embed the Brightback.js snippet in your site or app

Installation for the Chargebee Brightback.js snippet varies for regular web apps and Single Page Apps. For Single Page App instructions, scroll to the bottom of this article. If your customers can have multiple subscriptions requiring a few possible cancel options, follow the Single Page App instructions.

Regular web apps

To add Chargebee Retention to your cancellation flow, start with this minimal code to paste in the <head> section, just before the </body> tag on the page where your Cancel button is located. See the snippet in action here: Chargebee Retention Snippet Example.

<a id="bb-cancel" href="/fallback">Cancel</a>
<script type="text/javascript" src="https://app.retention.chargebee.com/js/current/brightback.js"></script>
<script type="text/javascript">
  if (window.Brightback) {
    window.Brightback.handleData({
    app_id: 'RETENTION_APP_ID',
    email: 'UNIQUE_USER_EMAIL,
    save_return_url: '',
    cancel_confirmation_url: '',
    account: {
      internal_id: 'UNIQUE_USER_ID'
    }
  });
  }
</script>

Replace the APP_ID with your company's unique ID, which you can request from your CSM, and populate the email (optional) of the user and internal_id of your customer's account.

The minimum fields required to generate a Chargebee Retention cancel experience without a billing provider enrichment are as follows:

if (window.Brightback) {
    window.Brightback.handleData({
     app_id: 'RETENTION_APP_ID',
     email: 'UNIQUE_USER_EMAIL',
     account: {
      internal_id: 'UNIQUE_USER_ID'
     }
    });
  }
What are the standard Chargebee Brightback.js snippet fields?

Standard data fields in Chargebee Retention:

Field Description
app_id This is your unique app ID that tells Chargebee Retention which company's cancellation experience to display. You can get your app ID from your dedicated CSM.
subscription_id The subscription ID of your customer in your billing system (Stripe, Recurly, Chargebee).
first_name Customer's first name.
last_name Customer's last name.
full_name Customer's full name.
email Customer's email.
save_return_url Return URL from Chargebee Retention for customers who click Never mind.
cancel_confirmation_url Return URL from Chargebee Retention for customers who cancel.

Note:

If you want a richer cancellation experience for your customers, customize your code with desired customer attributes.

2. Add personalized data to capture and send to Chargebee Retention

Adding customer attributes allows for:

  • Customizing customer data for a personalized experience.
  • Grouping customers based on custom attributes (like big spenders vs. freebies).
  • Reporting for deeper insights.

To add more data for personalization, simply edit your JS snippet to include those fields. Once you define which fields you'd like to include with your Customer Success Manager, we're happy to generate your unique code so all you need to do is copy and paste just before the closing </body> tag on the page where your Cancel button is located.

An example snippet looks like this:
<!-- Chargebee Retention | the customer retention company -->
<!-- * = required fields -->
<script type="text/javascript" src="https://app.retention.chargebee.com/js/current/brightback.js"></script>
<script type="text/javascript">
  if (window.Brightback) {
    window.Brightback.handleData({
      app_id: 'APP_ID',                      //*  
      subscription_id: 'SUB_ID'              //*               
      first_name: 'John',                 
      last_name: 'Doe',                   
      email: 'jdoe@example.com',          
      save_return_url: 'https://site.com/account/',        
      cancel_confirmation_url: 'https://site.com/account/cancel',  
      account: {
        company_name: 'Acme Products',    
        company_domain: 'acme.com',       
        internal_id: 'USER_ID',              //* 
        billing_id: 'cus_FfV4CXxpR8nAqB', 
        plan: 'enterprise',
	plan_term: 'monthly',               
        value: 1000.00,                   
        created_at: 1312182000            
      }
    });
  }
</script>
Optional Fields

Here's a list of some built-in, but optional, standard fields we recommend pulling in under the account section of the code:

When your customer started the subscription. Helpful to capture for creating customer age profiles.

Field Description
company_name Your canceling customer's company name. Recommended for reporting for B2B businesses.
company_domain Your canceling customer's website. Recommended for reporting for B2B businesses.
plan_term The renewal period for the subscription (yearly, weekly, monthly).
created_at When your customer started the subscription. Helpful to capture for creating customer age profiles.
internal_id Your customer's unique ID.
plan Used for reports or creating personalized offers by plan type, like enterprise or freemium.
billing_id Customer billing ID.
value Revenue number to be displayed in reports or used for audiences.
Adding Custom Data

Each business is unique, and that means providing unique cancellation experiences based on how it's important for your business to categorize your customers. Learn more about which custom data fields Chargebee Retention suggests to tailor Chargebee Retention for your subscription business.

Once fields are defined, add to your Chargebee Retention JS snippet in a custom section below the default fields.

Example snippet of a complete code snippet below:
<!-- Chargebee Retention | the customer retention company -->
<!-- * = required fields -->
<script type="text/javascript" src="https://app.retention.chargebee.com/js/current/brightback.js"></script>
<script type="text/javascript">
  if (window.Brightback) {
    window.Brightback.handleData({
      app_id: 'APP_ID',                    
      first_name: 'John',                 
      last_name: 'Doe',
      full_name: 'John Doe',                   
      email: 'jdoe@example.com',          
      save_return_url: 'https://site.com/account/',       
      cancel_confirmation_url: 'https://site.com/account/cancel',  
      account: {
        company_name: 'Acme Products',    
        company_domain: 'acme.com',       
        internal_id: '1234AZ55',          
        billing_id: 'cus_FfV4CXxpR8nAqB', 
        plan: 'enterprise',
	plan_term: 'monthly',               
        value: 1000.00,                   
        created_at: 1312182000            
      },
      custom: {
        activity: {
          emails: 42085,  //For loss aversion card
          templates: 86,  //Values populated via a back-end
          contacts: 102546                
        }
      }
    });
  }
</script>

You'll find the custom attributes defined in the custom section of the code:

custom: {
   activity: {
     emails: 42085,                  //   For loss aversion card
     templates: 86,                  //   values populated via a back-end
     contacts: 102546                //   
   }
 }

3. Link the code to your cancel button

To redirect your canceling customer through the Chargebee Retention cancellation experience, identify the button or link that is clicked by the user when initiating a cancelation request. Give the cancel link or button in your app an ID of bb-cancel. Chargebee Retention will replace the href if we are able to render an exit experience based on the provided data following the call to window.Brightback.handleData. You should maintain a fallback that conforms with your existing workflow in the case that Chargebee Retention is unable to render an exit experience.

Example

<a id="bb-cancel" href="/fallback">Cancel</a>
Making precancel requests without using Chargebee Brightback.js

Chargebee Brightback.js is not required to create cancel sessions in Chargebee Brightback. You may also make your own POST request to our precancel endpoint. As long as you include the required properties and a valid app_id, our server will respond with a unique session URL for your user. More information can be found here.

Installing the code into a Single-Page App

If your app is characterized by asynchronous JS and few page refreshes, you may need to integrate Chargebee Retention in a slightly different way. See the snippet in action here: Chargebee Retention Single Page App JSFiddle

Include the Chargebee Retention JS library file in your HTML head element or however your framework (React, Angular, etc.) sets up the environment. This will bind a few functions to window.Brightback.

When your application is in a state where the user is presented with the cancelation option, you should set up the Chargebee Retention state, so that you can send the user immediately to the Chargebee Retention experience when the user clicks. This is achieved by sending the user's data to the window.Brightback.handleDataPromise method.

For example

const p = window.Brightback.handleDataPromise({
      app_id: 'APP_ID',                    
      first_name: 'John',                 
      last_name: 'Doe',
      full_name: 'John Doe',                   
      email: 'jdoe@example.com',          
      save_return_url: 'https://site.com/account/',       
      cancel_confirmation_url: 'https://site.com/account/cancel',  
      account: {
        company_name: 'Acme Products',    
        company_domain: 'acme.com',       
        internal_id: '1234AZ55',          
        billing_id: 'cus_FfV4CXxpR8nAqB', 
        plan: 'enterprise',
	plan_term: 'monthly',               
       value: 1000.00,                   
       created_at: 1312182000     
  },
  custom: {
    activity: {
      emails : 42054,
      templates : 81,
      contacts : 102444
    }
  }
});

This will return a promise to a JSON validation object. The purpose of this step is to verify Chargebee Retention has sufficient data to render a cancelation experience prior to attempting to redirect the user. A successful validation object will look like this example:

{
  "valid": true,
  "url": "https://app.retention.chargebee.com/examplecompany/cancel/LAz4pVyRkq"
}

When the user clicks on your cancel button, you could redirect them as in the following example:

p.then((success) => {
  if (success.valid) {
    window.location.href = resp.url;
  } else {
    //use your current cancelation flow
  }
});

Example of a "bare minimum" installation

The following is an example of the data that is strictly required for the integration to function properly. While some of the personalization and loss aversion would fall back to defaults, this represents the place to start to get immediate value from an integration:

<a id="bb-cancel" href="/fallback">Cancel</a>
<script type="text/javascript" src="https://app.retention.chargebee.com/js/current/brightback.js"></script>
<script type="text/javascript">
  if (window.Brightback) {
    window.Brightback.handleData({
      app_id: 'APP_ID',
      email: 'jdoe@example.com',
      account: {
        internal_id: '1234AZ55'
      }
    });
  }
</script>

Just replace the APP_ID, and populate the email (optional) of the user and internal_id of your customer's account, and you're ready to go!

Example of a "bare minimum" installation with a supported billing system

If you are using Stripe, Recurly, or Chargebee, you'll only need to send the subscription ID of the cancel request. That will allow us to look up your user, cancel their subscription, or apply any offers if applicable.

<a id="bb-cancel" href="/fallback">Cancel</a>
<script type="text/javascript" src="https://app.retention.chargebee.com/js/current/brightback.js"></script>
<script type="text/javascript">
  if (window.Brightback) {
    window.Brightback.handleData({
      app_id: 'APP_ID',
      subscription_id: '96SL3sJRIRmi8KJWR'
    });
  }
</script>

Loading Chargebee Retention experiences in an iframe.

Wrapping the Chargebee Retention experience in an iframe is possible, but due to our security policy, you must have a vanity domain in place that matches the TLD of the referring site.

Was this article helpful?