Docs
Chargebee Retention integrates directly with Recharge to enrich sessions with Billing Data and to process cancels and Offers directly via the Recharge APIs. In order to integrate Recharge and Chargebee Retention, you will need to install the Chargebee Retention code snippet into your Recharge "Theme Editor." Fear not, while the word "code" sounds scary, this is an easy install that we provide a template for below. This article will walk you through the steps you need to go through to Integrate Recharge + Chargebee Retention and get started saving customers!
We will break the integration down into three main steps:
You will need to complete each of the ^ steps to get Chargebee Retention ready to launch with Recharge. We cover how to setup Chargebee Retention to optimize for Deflection in this article.
The first step to get Chargebee Retention integrated with Recharge is to generate an API key in your Recharge App and connect it to Chargebee Retention. To do so, navigate to Recharge > Apps > API Tokens.
Note: Depending on your version of ReCharge you may see two different API token options. If you see two options you need to choose Admin API Token
Here you will have the option to Create an API token. Be sure to give it the following Permission Scope's to ensure all of the Chargebee Retention features work.
This will allow us to Enrich sessions with customer data, process cancels and process offers in billing. It will also enable the future Revenue Impact reporting features that will be coming down the road. Once you have your keys generated, copy them and head over to the Chargebee Retention App to connect the Integration via Settings > Integrations > Billing Integrations
Here we give you the option to plug in a live key and a test key. We recommend linking your test key to a test billing site that can be used with the Sample Session generator to test the Manage Cancels and Manage Offer features of your integration. We cover this in more detail in this article.
Once you have connected the API keys you will see that fields have been mapped and you can now "Manage the integration." You are now ready to setup Enrichment, Manage Cancels and Manage Offers.
The Recharge Billing Integration comes with three main features out of the box, Enrichment, Manage Cancels and Manage Offers. These features give you all the tools that you need to configure Chargebee Retention to update Recharge based on the outcomes (canceled, accepted an offer) that occur in the Cancel Experience.
The Recharge Enrichment feature allows you to map fields from Recharge directly into Chargebee Retention. These fields can then be used to define Audiences for Targeting and to personalize the Cancel Experience. Chargebee Retention will automatically connect with Recharge when you enable the integration and map a set of standard fields from Recharge into Chargebee Retention. You can add additional fields via our Custom Field mapping.
Here is a list of the Chargebee Retention pulls from Recharge:
If there is a field you are looking for that is not listed here, please contact retention-support@chargebee.com
Once you have mapped your fields, they can be used in Page Personalization and Audience definition.
Once you have your enrichment integration enabled, the next step is to determine how you would like to process your Cancels and Offers in Recharge. To do so, navigate to Settings > Setup > Billing system.
Here you will see that Enrichment is enabled automatically. You can also flip on Manage offers and Manage cancels.
When you enable Manage cancels, you will get the option to either "Cancel all subscriptions" or individual subscriptions and determine if a subscription is canceled at the end of the term or immediately. You will want to align these settings to match how you handle cancelations in your Recharge account today.
Here you also have the option to set your cancels to be at the Page-level or the App-level. When Page-level is selected, you manage the individual processing of each pages cancels in the Page Settings tab within the page editor.
Once you have enabled Cancel management, the final setting you will want to enable is Offer management in Chargebee Retention.
When you enable this, it will allow you to connect Offers in the Chargebee Retention Offer Library with Recharge directly so they are processed via API. We currently support Discounts, Pause/Skip, Plan Change, and Gift offers with our native integration and are in the process of adding more Offer Types. If you have a particular type of offer you would like to see integrated with Recharge, please contact retention-support@chargebee.com
Discount Offers will pull in a coupon code that you generate in Recharge and sync it to the Offer in Chargebee Retention. When this offer is accepted, the coupon will be directly applied to the subscription in Recharge.
You can present a pause offers that allows your customers to pause their subscription based on a time period or number of orders. For duration-based pauses, you can configure pause duration based on days, weeks, months, or years.
For skip order offers, you can specify the pause duration based on the number of upcoming orders to skip.
For plan change offers, set up the new plan to be applied by specifying the product, frequency, or both. You will need to enter the external variant ID and/or external product ID.
For gift offers, you can provide customers with a free gift when they continue their subscription. You will need to enter the external variant ID for the gift when setting up the gift offer.
If you have any questions about how to enable our existing Manage offers feature with Recharge or would like to request that additional Offer support is added, please contact retention-support@chargebee.com.
Chargebee Retention supports Manage Cancels and Manage Offers for Recharge pre-paid subscriptions where the billing frequency differs from the shipment frequency. For example, a customer pays for 6 month subscription upfront and receives a shipment every month for the next 6 months. For Manage Cancels, we support processing cancels at end of term through the API. This means customers who cancel will continue to receive shipments they paid for and will not be charged at the next renewal. For Manage Offers, we currently support discount and pause offers.
The final step to get Chargebee Retention ready to launch on Recharge is to install the Cancel Button into the Recharge Theme Editor. In this example we're using the "Novum" theme from ReCharge out of the box with Recharge hosting. Navigate to Recharge > Storefront > Theme Editor.
1) Head to your recharge storefront and select the "Theme Editor"
2) Duplicate the theme you would like to edit. If you prefer to make your changes locally you can alternatively download the theme and then import it later.
3) Click "Edit code" on your duplicated theme.
4) Navigate to the page where your cancel button or link currently lives. We're going to replace the default Recharge cancellation modal with Chargebee Retention so we're editing "subscription.html".
In the code you'll find Recharges link which you can comment out or delete entirely. In this example, we've commented it out so it will not be rendered on the page but the best practice is to remove it entirely before you publish the theme.
5) Add the Chargebee Retention button code in its place. You'll notice we've left the theme's default styling in place to match the look and feel of the page. We've assigned the button with the id selector of "bb-cancel" to tell Chargebee Retention which button should launch the Chargebee Retention experience.
<!-- Chargebee Retention button -->
<button id="bb-cancel" class="rc_btn--link text-uppercase title-bold" href="{{ subscription.id | subscription_cancel_url }}">Cancel subscription</button>
<script type="text/javascript" src="https://app.brightback.com/js/current/brightback.js?compiled=true"></script>
<!-- End Chargebee Retention button -->
6) Now that we're done updating the button itself we'll need to drop in the Chargebee Retention code snippet to fetch a unique session URL for our canceller to land on when they click cancel. Navigate to somewhere below the button and add the Chargebee Retention script elements to the source code of the page. The bottom of subscription.html should work just fine for the Novum theme. This script should eventually reside in just the BODY of the page and below the button, not the in the HEAD of this page or the entire site.
Populate the values for the Chargebee Retention data object with properties from Recharge's built-in API's and add in any custom keys if needed. We're only showing a few examples here but you can include any key:value pairs in either
<!-- Chargebee Retention precancel -->
<script type="text/javascript">
const cancelURL = "{{ subscription_list_url }}";
const saveURL = "{{ subscription.id | subscription_url }}";
if (window.Brightback) {
window.Brightback.handleData({
app_id: "RETENTION_APP_ID",
subscription_id: "{{ subscription.id }}",
save_return_url: saveURL,
cancel_confirmation_url: cancelURL
});
}
</script>
<!-- End Chargebee Retention precancel -->
Only the app_id and subscription_id are required fields here. You can locate your Chargebee Retention app_id in the url for your application, see highlighted screenshot below.
Everything else is optional and can be populated to further enhance the cancel experience. The save and cancel return URLs are the links that your customers will be routed to when they leave the cancel experience, so it is important to ensure you have proper links setup here or to override them via the page settings. We cover this in more detail in this article. If you want some examples of the types of fields that customers typically add when integrating Chargebee Retention, we cover that in more detail in this article.
Once you have integrated the Chargebee Retention Cancel button into your Theme Engine subscription.html file you are ready to publish your new Cancel Experience. You will want to make sure that you have updated your Branding and published your Targeting in your Chargebee Retention app before doing so. Then return to your Recharge app and Preview the theme.
Here you should be able to see the Chargebee Retention cancel button that will route you to the Chargebee Retention Cancel Experience. Once you have previewed the theme, you can publish it live via the Theme editor menu.
The Retained Revenue Impact Reporting feature adds Repurchase Metrics such as First Time Repurchase Revenue, Total Repurchase Orders, Average Repurchase Orders, Cumulative Retained Revenue and Winback Metrics such as First Winback Rate, Total Winback Orders, Average Winback Orders, Cumulative Winback Revenue. This allows you to quantify the financial impact of your retention efforts further so that you can understand how Deflects and Cancels are converting into downstream orders.
It also enables the Retained Revenue Cohort Report, which is critical to understanding how your Deflects in Retention drive downstream revenue impact for your business.