How to setup Chargebee Retention in Chargebee Billing via the Retention API?

Modified on: Tue, 4 Oct, 2022 at 5:40 PM


How to set up Chargebee Retention in Chargebee Billing via the Retention API?

How to integrate Chargebee Retention using API?


Chargebee Billing merchants who are using APIs to manage their subscriptions can now integrate with the Chargebee Retention API to initiate a Chargebee Retention cancel session. This approach is an alternative to the Chargebee Retention.JS and can be leveraged to quickly add Chargebee Retention to your existing Chargebee Billing setup or a new billing site deployment. The documentation on how to set up this API can be found in Chargebee's API docs


This API allows you to initiate a cancel session by securely passing Chargebee Retention a subscription ID, which allows us to return the Cancel Session URL that will be served to the customer when they hit the cancel button on your account management page. When you integrate Chargebee and Chargebee Retentionwe will map your Billing Fields into Chargebee Retention to be used in page personalization and audience definitionYou can also pass additional custom fields via the Retention API as well.

In order to start sending traffic to Chargebee Retention, you will need to install the Retention API and complete the remaining steps to build out your Chargebee Retention Cancel Experiences. 

How Cancels are Processed via Chargebee Retention

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 Retention integration. To test the integration, you have two options, a Sandbox app or our Sample Session Generator. 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. This will allow you to run a full test starting on your Account Management page without having it impact your production customers. 

If you do not have access to a Sandbox app, you can integrate your test API Key into the Chargebee Test site in your Chargebee Retention settings and then use the Sample Session Generator to trigger a cancel session. 

To do so, first, add your Test site integration details into the Settings > Integrations tab

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

Publishing your Retention API Cancel Experience

Once you have completed testing, you are ready to enable Cancellation via Chargebee Retention for your live Chargebee site. To do so you will need to update the API to ensure traffic is being sent to your production site. We cover how to do this in the API docOnce this is done, your Chargebee Retention Integration is live and your Chargebee Retention Dashboard will start to populate with data! 

If you need assistance getting started with the Chargebee Retention API, please reach out to

Related Articles

How to configure Enrichment in Chargebee Retention?

How does the Repurchase Revenue Impact Reporting?  

What is Chargebee Retention used cases? 
Define the Chargebee Retention Testing Methodology

Did you find it helpful? Yes No

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