How to setup Chargebee Billing with Chargebee Retention for live site?

Modified on: Fri, 7 Oct, 2022 at 8:36 PM


How to set up Chargebee Billing with Chargebee Retention for the Live site?

What is the process to follow Chargebee Retention integration for active sites?

Steps to get Chargebee Retention ready to launch for Billing Merchants


To get started with Chargebee Retention, you will first need to sign-up for an account. You can do so directly in your Chargebee App under Configure Chargebee > Customer Facing Essentials > Chargebee RetentionOnce you have done so, you will be ready to configure the integration. Below are the steps required, along with a guide for each step. 

  1. Connect your Chargebee Retention app to the Chargebee site via signup flow
  2. Enable Manage Cancels and Manage Offers in your Chargebee Retention settings
  3. Update your logo and branding in Chargebee Retention
  4. Configure your Cancel Pages with Survey Reasons and Loss Aversion Cards
  5. Determine offers to test and add to pages
  6. Publish your targeting
  7. Determine how you will initiate a Chargebee Retention session
    1. via the customer portal
    2. via the Retention API
    3. via the Chargebee Retention.JS
  8. Test and deploy the cancel experience


Step 1: Connect your Chargebee Retention app to Chargebee via signup flow

Signup flow within Configure Chargebee

Chargebee merchants can now integrate their site with Chargebee Retention via the Configure Chargebee Settings. Doing so will create a free 30-day trial of Chargebee Retention's Essentials plan that is automatically linked to your Chargebee site via an API key we create for you. 

Navigate to Configure Chargebee > Customer-Facing Essentials and select Retention via Chargebee Retention

This will take you to a landing page where you can initiate this signup flow. You will be prompted to Create your company where you will provide a company name, company key (must be unique and will be autogenerated from the name), and domain. 

Once you have provided these, we will ask you to create a user login with Chargebee Retention either using google authentication or a username and password. 

Once you have created your use, you will be routed to the Chargebee Retention dashboard and your site will be connected to Chargebee Retention via an API key we automatically generate. 

Once you have connected the integration, Chargebee Retention will automatically enable Enrichment and automap fields from Chargebee Billing into your Chargebee Retention App. 

You can view and update the default field mappings under settings or you can continue onto the next step and start configuring your Chargebee Retention Cancel Experiences. 

Note: You can start with a test site and use this to test the integration and then later swap out the API keys for your live site. To update the API keys, visit the Chargebee Retention Settings > Integrations where you can manage this

Note: If you signed up for a Chargebee Retention Trial prior to 7/1 you may already have a Chargebee Retention App. Going through the signup flow will not work in this case. If you find this to be the case, please contact and we will help you get integrated

Step 2: Enable manage cancels and manage offers in your Chargebee Retention settings

Once you have integrated Chargebee, we will display the configurations you need to determine how Chargebee Retention processes Cancel and Offer in your systems. To do so, navigate to Settings > Setup > Billing System in Chargebee Retention. 

Here you will see the option to configure the four features we support for Chargebee (Attribution, Enrichment, Manage offers, Manage cancels). We recommend that you enable all four of these features by default, as this will give you the full power of the integration between Chargebee Retention and Chargebee Billing. 

Here you have the option to define how you process cancelations in Chargebee via our Manage cancel API. The settings you choose here will override the settings in your Configure Chargebee page when you have traffic going to Chargebee Retention. You can choose to apply these settings at the App Level or customize them at the page level so that some pages can be customized for a specific audience. 

Once you have configured these settings, you will be ready to move on to Step 3 and start editing your Branding and Cancel Experiences. 

Step 3: Update your logo and branding in Chargebee Retention 

The first step once you have completed the configurations for your Chargebee Retention setup is to add your logo and update your Branding in the Chargebee Retention Branding Manager. Navigate to Experiences > Branding > Edit Branding to access this editor. 

For more details on what you can do with our Branding Manager, visit this link. Once you have the page looking good, you are ready to move on to Step 4 and start editing the actual page content itself. 

Step 4: Configure your Cancel Pages with Survey Reasons and Loss Aversion Cards

The Page Manager is where you can edit your individual Chargebee Retention pages and copy them to create new pages. 

We have designed this editor to allow you to easily copy and create new pages, so we suggest you start by editing the Holdout page and first test page, then you can copy these to create additional pages. 

The Page Editor allows you to configure all the individual components of your Cancel Page, starting with the Loss Aversion cards displayed at the top of the page and continuing on through the Survey and Page Footer. Click this link to know more about this editor.

Don't forget to set up your Page settings, as this is where you configure the URLs that canceled and saved users are sent to when they leave the Chargebee Retention Page. 

You will also want to take some time to ensure that you are adding the right set of Cancel Reasons to your Page. The Chargebee Retention Survey Reason library helps you with categorizing the top cancel reasons we see across various subscription business models. Once you have configured this initial page, you can create copies of it to swap out different Offers and/or Loss Aversion cards for testing. 

Step 5: Determine Offers to Test and Add to Pages

The power of Chargebee Retention comes in the ability to mix and match different Offers to test and determine which experiences will drive the highest Deflect and Save rates for various audiences going through your cancel flow. To do so you will want to visit the Chargebee Retention Offer Library and browse the various options available to you. 

Chargebee Retention has defined six categories of Offers: Pauses, Discounts, Extensions, Plan Changes, Feedback, and Support & Training. We suggest to new customers that they pick a few offers from each category so they can test them against each other and a no-offer holdout to determine which performs best. We cover this in more detail in our Creating a Random Offer Test article. 

We integrate directly with Chargebee to update subscriptions with Discounts, Pauses, Extensions, and Plan Changes. You can configure these in the Billing tab within the Offer Editor

Note: You need to ensure that you have set up your Coupons in Chargebee Billing to apply to the eligible plans. If you try to apply a coupon offer that is not set as eligible for all plans, you will need to define an Audience in Chargebee Retention with that plan as the criteria and only apply the discount offer to those who are eligible for it.

Step 6: Publish your Targeting

Once you have added offers to your pages, it is time to navigate to the Targeting tab and define the rules for how your pages will be displayed to end-users. Here you can either choose to target pages by specific percentages or by audience rules. 

If you don't know if you should start with audiences or not, we typically advise you to start simple and add complexity as you learn. You should only include an audience to start if you do not want to show a certain offer to a specific audience, ex: a monthly skip Offer does not apply to Annual Plans. Otherwise, we recommend testing offers first, then adding audiences to your testing down the road, per the Chargebee Retention Testing Methodology.

Step 7: Determine how you will initiate a Chargebee Retention Session

There are two ways to initiate a Chargebee Retention Session, depending upon who you are managing Subscriptions in Chargebee. 

Via the Chargebee Customer Portal

If you are using the customer portal to manage your customer's subscriptions, then you can integrate Chargebee Retention without writing any code.

To do so, all you need to do is navigate to your Configure Chargebee > Checkout & Self-Serve Portal and enable the toggle for "Cancellation via Chargebee Retention.  When you enable this setting, customers who hit 'Cancel subscription' in the self-serve portal will be routed to your Chargebee Retention page based on the logic you have defined in Step 6.

When you have enabled this setting, we will hide the remainder of the cancellation settings here as they are now handled in Chargebee Retention.

Before you do so, you will want to ensure that you do not have Reason Codes set to required in your Chargebee settings. Navigate to Configure Chargebee > Advanced Settings > Reason Codes > Subscription Cancellation and ensure this is not set to mandatory. Once you have done so, you are ready to navigate to Step 8

Via the Chargebee Retention.JS

If you are not using the Chargebee Customer Portal to manage subscriptions, you will need to add the Chargebee Retention.JS to initiate a Cancel Session. You will need to ensure you pass the Chargebee Subscription ID for that subscription via the Chargebee Retention JS. 

This ChargeBee Subscription ID is captured dynamically from the Chargebee Retention.js code snippet (or from your Salesforce CRM account) when the user first initiates a session by clicking to cancel. If you haven't already, review the documentation on how to install the Chargebee Retention javascript snippet.

If you need assistance setting up the Chargebee Retention.JS, please reach out to

Step 8: Test and Deploy the Cancel Experience 

Once you have determined how you will initiate a Chargebee Retention session, you are ready to test and deploy your cancel experience. Depending on how you are setting up the flow, there are a few different options for testing. We cover these in more detail in this article.

Once you are satisfied with your testing, you can deploy the cancel experience live to your customers. If you are a portal user, you can do so from Configure Chargebee > Checkout & Self-Serve Portal

If you are using the JS, you will need to update your account management page to route traffic to Chargebee Retention when users hit the cancel button. Once this is done, you can sit back and watch the traffic come into your Chargebee Retention Dashboard and Reports. 

Related Articles

How to test the Chargebee retention cancellation process? 

How to configure Enrichment in Chargebee Retention? 

How to setup Chargebee Retention via the Retention API

How does the Repurchase Revenue Impact Reporting? Updated 

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.