How to setup Chargebee Retention for the Chargebee Billing self-serve portal?

Modified on: Wed, 10 May, 2023 at 2:34 PM


How to set up Chargebee Retention for the Chargebee Billing customer portal?

How to configure Chargebee retention on the Chargebee self-serve portal?

How to perform end-to-end testing of Retention in Chargebee Billing?

How do I get to the retention portal?


Once you configure Chargebee Retention from Settings > Configure Chargebee > Retention, you can integrate Chargebee Retention on the the customer portal, by navigating to Settings > Configure Chargebee > Checkout & Self-Serve Portal > Portal > Enable Cancellation via Chargebee Retention > Enable from Chargebee Billing.


If you are using the Chargebee billing self-serve portal to manage your customers' cancellations via Chargebee Retention you can configure Cancel Experience when they click Cancel. You can deploy a Chargebee Retention Cancel Experience without writing any code. To integrate Chargebee Retention on customer portal, navigate to Settings > Configure Chargebee > Checkout & Self-Serve Portal > Portal > Enable Cancellation via Chargebee Retention > Enable

If you do not see this option, ensure you enable Allow customers to cancel subscriptions from Settings > Configure Chargebee > Checkout & Self-Serve Portal > Portal from Chargebee Billing.

In order for this integration to work, you will need to go through the steps outlined in this link to set up your Chargebee Retention account to work with Chargebee Billing. 

How Cancels are processed via Chargebee Retention?

You can configure the Cancellation process, by navigating to Configure Chargebee > Chargebee Retention > Launch Retention App. Then Navigate to Settings on the left-hand action menu > Settings > Setup > Billing system

It is important that you map the settings for how you want to handle subscription cancellation from Chargebee Billing to Chargebee Retention. These settings will override what you have configured in Chargebee Billing when you route traffic to Chargebee Retention.

Reason Codes not set to Mandatory

Navigate to Configure Chargebee > Advanced Settings > Reason Codes to ensure that this setting is not turned on. If it is, Chargebee Retention will not be able to process the results of your cancels and an error will be logged in the Activity Log. 

Testing your Chargebee Retention Integration

Once you have completed your setup in Chargebee Retention, you are ready to test and then deploy your Portal integration. If you are on Chargebee Retention Performance Plan we provide access to a Sandbox app. You can integrate your test site ID and test API key into this Sandbox app and use it to generate a sample session and test the integration end-to-end. 

If you do not have access to a Sandbox App, you can integrate your test API Key into the Chargebee integration and use our Session Generator / Test Site Portal preview to run a test session. 

To do so, first, add your test site integration details into the Settings > Integrations tab on the Chargebee Retention page. 

Then you can navigate to Targeting > Session Generator to initiate a sample test session. 

Note: Test sessions will not count against reporting, but we will process the events associated with these and update your billing systems accordingly. If you test against a live site key, ensure that you are using a test account when doing so because these tests will update your Chargebee subscription record.

You also can test from Chargebee directly using the Portal Preview on your test site. You will have to enable the toggle to ensure that traffic is going to the Chargebee Retention page on your test site. When this is enabled, users will be re-directed to Chargebee Retention when they select to cancel their subscription. Once you are satisfied with your tests, you can go into your live site and enable the Chargebee Retention Integration. 

If the Chargebee Retention App is integrated incorrectly (ex: a read-only API key has been configured) and the above setting is enabled, Chargebee will fall back and cancel the subscription immediately. You will notice when testing this integration that clicking cancel subscription in the portal preview does not route to the Chargebee Retention page, but falls back on the feedback form

Publishing your Portal Cancel Experience

Once you have completed testing, you are ready to enable cancellation via Chargebee Retention for your live Chargebee site. Doing so will route your customers to the Chargebee Retention Cancel Page instead of the Chargebee portal cancel experience (test).

Once this is done, your portal integration is live and your Chargebee Retention Dashboard will start to populate with data. Refer to this link for more information.

If you need assistance getting started with the Chargebee Retention self-serve portal, please reach out to

Related Articles

What is Chargebee Retention? 

What are the core billing features of Chargebee Retention? 

How to Integrate Chargebee Retention and Chargebee Billing? 

Did you find it helpful? Yes No

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