Steps to launch for Chargebee Billing Merchants 

To get started with Chargebee Retention, you will first need to sign-up for an account. You can do so from directly in your Chargebee App under Configure Chargebee > Customer Facing Essentials. Once 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 Chargebee Site via Signup Flow
  2. Enable Manage Cancels and Manage Offers in your Chargebee Retention Settings
  3. Update your Logo / Branding in Chargebee Retention
  4. Configure your Cancel Pages w/ 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

Connect your Chargebee Retention App to Chargebee via Signup Flow 

Step 1

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 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 user name 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. You can read more about this signup flow in here.

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.


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.


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.

Enable Manage Cancels and Manage Offers in your Chargebee Retention Settings 

Step 2

Once you have integrated Chargebee, we will display the configurations you need to determine how Chargebee Retention processes Cancels and Offers 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.

Update your Logo / Branding in Chargebee Retention 

Step 3

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 article. Once you have the page looking good, you are ready to move on to Step 4 and start editing the actual page content itself.

Configure your Cancel Pages w/ Survey Reasons and Loss Aversion Cards 

Step 4

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. We cover this editor in detail in this article, which we suggest reading before diving into configuring your first page. It is important that you spend some time here to go through each section and configure it as you would like.

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 also will 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 is here to help, where we have categorized 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.

Determine Offers to Test and Add to Pages 

Step 5

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 typically suggest to new customers that they pick a few Offers from each category 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.


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.

Publish your Targeting 

Step 6

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 %s or by Audience Rules.

If you don't know if you should start with Audiences or not, we typically advice 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.

Determine how you will initiate a Chargebee Retention Session 

Step 7

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 now 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.

If you have manually integrated the Chargebee Customer Portal using iframe, confirm your integration includes chargebee.js in the HTML header script as described in this article. 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

Test and Deploy the Cancel Experience 

Step 8

Once you have determined how you will initiate a Chargebee Retention Session, you are ready to test and deploy your Cancel Experience. Depending upon 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.

That's all there is to it. If you need help with any of the ^, please reach out to and we will assist you.

Was this article helpful?