How to setup Chargebee Retention via the Retention API
Chargebee 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 setup 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 end user when the hit the cancel button on your account management page. When you integrate Chargebee and Chargebee Retention, we will map your Billing Fields into Chargebee Retention to be used in page personalization and audience definition. You 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 in 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 API doc. Once 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 email@example.com.