Installing the Chargebee Retention.js Snippet

Initializing a session for your canceller in Chargebee Retention starts by making a precancel request to Chargebee Retention and sending your user to the unique session URL that is returned in the response.

Integrating Chargebee Retention into your site or app requires a technical install that starts with embedding the Chargebee Retention.js code snippet to the page where your cancel button lives or by making a precancel request, and then configuring how you will process cancels and offers.

When it comes to designing the cancel page experience itself, your Admin will use the Chargebee Retention Experience Manager to design the retention strategy, brand the page, and define loss aversion, offers, and survey questions.

Chargebee Retention.js Overview

The Chargebee Retention .js snippet runs when your customer clicks the cancel button and returns the URL of a customized cancel page to redirect your user to, while working all sorts of magic like a) pulling custom data in about your canceling customer, b) using that custom data to personalize the cancel experience (e.g. present dynamic offers, loss aversion carts, or alerts), and c) segmenting your customer based on standard or custom data fields.

Here's a visual of how we use the Chargebee Retention JS snippet to personalize your Chargebee Retention Page.

You can email Chargebee Retention.js installation instructions to your developer here.

How to get Chargebee Retention.js up and running in three steps:

1. Embed the Chargebee Retention JS snippet to your site or app on the page where your customer will click 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 Retention suggested data fields)
3. Link the code to your cancel or downgrade button

Testing Chargebee Retention.js from localhost

By default and for security reasons, Chargebee Retention's server does not respond to a cancel initiation (precancel) request from localhost. If you are implementing a Chargebee Retention precancel request from your local machine during development, you will need to temporarily map a domain to your localhost to verify the XHR request or use a tunnel service like ngrok or localtunnel. Watch your network tab in the inspector to diagnose any additional issues.

127.0.0.1 localhost example.local

1. Embedding the Chargebee Retention.js snippet in your site or app

Installation for the Chargebee Retention JS snippet will vary 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, you'll need to 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 code, just before the tag on the page where your Cancel button lives. 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 Retention.js snippet fields?

Standard data fields in Chargebee Retention

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 tag on the page where your Cancel button lives.

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.

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.

<a id="bb-cancel" href="/fallback">Cancel</a>

Appendix

Making precancel requests without using Chargebee Retention.js

Chargebee Retention.js is not required in order to create cancel sessions in Chargebee Retention. You may also make your own POST request to our precancel endpoint. So 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 setup 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.