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
You can email Chargebee Retention.js installation instructions to your developer here.
How to get Chargebee Retention.js up and running in three steps:
- 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).
- Add custom data fields to enrich customer records, create audiences, and personalize content in Chargebee Retention (see Chargebee Retention suggested data fields)
- Link the code to your cancel or downgrade button
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
While step one and three is all that’s required to get immediate benefits from Chargebee Retention, step two will provide a richer, more personalized experience for your customers. Pro tip: scroll to the bottom of this article to see a "Bare Minimum" installation.
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.
<a id="bb-cancel" href="/fallback">Cancel</a> <script type="text/javascript" src="https://app.brightback.com/js/current/brightback.js"></script> <script type="text/javascript"> if (window.Brightback) { window.Brightback.handleData({ app_id: 'YOUR_CHARGEBEE_RETENTION_APP_ID', email: 'UNIQUE_USER_EMAIL, save_return_url: '', cancel_confirmation_url: '', account: { internal_id: 'UNIQUE_USER_ID' } }); } </script>
if (window.Brightback) { window.Brightback.handleData({ app_id: 'YOUR_CHARGEBEE_RETENTION_APP_ID', email: 'UNIQUE_USER_EMAIL', account: { internal_id: 'UNIQUE_USER_ID' } }); }<br>
What are the standard Chargebee Retention.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 |
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. |
Chargebee Retention
<!-- Chargebee Retention | the customer retention company --> <!-- * = required fields --> <script type="text/javascript" src="https://app.brightback.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>
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. |
Example snippet of a complete code below:
<!-- Chargebee Retention | the customer retention company --> <!-- * = required fields --> <script type="text/javascript" src="https://app.brightback.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>
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
<a id="bb-cancel" href="/fallback">Cancel</a><br></span>
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.brightback.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.brightback.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 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.brightback.com/js/current/brightback.js"></script> <script type="text/javascript"> if (window.Brightback) { window.Brightback.handleData({ app_id: 'APP_ID', subscription_id: '96SL3sJRIRmi8KJWR' }); } </script><br>
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.