Scope

How to integrate Chargebee Retention with the Recharge Theme Engine?

Summary

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 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. To do so, navigate to Recharge > Apps > API Tokens.

We will break the integration down into three main steps:

1. Connecting Recharge & Retention via API keys
2. Enabling Enrichment, Manage Cancels, and Manage Offers
3. Deploying the Retention Cancel Button into your Recharge Theme

Solution

You will need to complete each of the steps to get Retention ready to launch with Recharge. We cover how to set up Retention to optimize for Deflection in this article. 

Connecting Recharge & Retention via API Keys

The first step to getting Retention integrated with Recharge is to generate an API key in your Recharge App and connect it to Retention. To do so, navigate to Recharge > Apps > API Tokens.

Here you will have the option to Create an API token. Be sure to give it the following Permission Scope to ensure all of the 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 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 set up Enrichment, Manage Cancels, and Manage Offers.

Enabling 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 Retention to update Recharge based on the outcomes (canceled, accepted an offer) that occur in the Cancel Experience.

Mapping Fields with Enrichment

The Recharge Enrichment feature allows you to map fields from Recharge directly into Retention. These fields can then be used to define Audiences for Targeting and to personalize the Cancel Experience. Retention will automatically connect with Recharge when you enable the integration and map a set of standard fields from Recharge into Retention. You can add additional fields via our Custom Field mapping. 

Here is a list of the standard fields Retention pulls from Recharge:

Subscription
recharge.subscription.id
recharge.subscription.external_product_id.ecommerce
recharge.subscription.charge_interval_frequency
recharge.subscription.quantity
recharge.subscription.order_interval_unit
recharge.subscription.value
recharge.subscription.price
recharge.subscription.next_charge_scheduled_at
recharge.subscription.status
recharge.subscription.customer_id
recharge.subscription.product_title
recharge.subscription.created_at

Plan
recharge.product_id
recharge.product_name
recharge.plan_interval
recharge.interval_length

Customer
recharge.address.country
recharge.billing_id
recharge.customer.first_name
recharge.customer.last_name
recharge.customer.owner_email
recharge.customer.create_date
recharge.customer.first_purchase_date

Address
recharge.address.state
recharge.address.country

Coupons
recharge.coupon_ids

Once you have mapped your fields, they can be used in Page Personalization and Audience definition

Processing Cancels in Recharge

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 page cancels in the Page Settings tab within the page editor. 

Processing Offers in Recharge

Once you have enabled Cancel management, the final setting you will want to enable is Offer management in Retention.

When you enable this, it will allow you to connect Offers in the Retention Offer Library with Recharge directly so they are processed via API. We currently support Discounts and Pause 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

Discount Offers will pull in a coupon code that you generate in Recharge and sync it to the Offer in Retention. When this offer is accepted, the coupon will be directly applied to the subscription in Recharge. 

Click the dropdown to see a list of available coupon codes in your Recharge App. If you would like to add more, navigate to Recharge > Discounts and create a new coupon code.

Note: It may take a minute for your Discount code to sync into Retention once it is created

Pause Offers

With the integrated Pause Offer, we give you the option to select the Pause duration and Pause interval in Recharge. This will directly reflect how long we pause the subscription for. We provide the option to choose a daily, weekly, monthly and yearly interval.

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

Deploying the Retention Cancel Button into your Recharge Theme Editor

The final step to get 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 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 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 Retention which button should launch the Retention experience.

     <!-- Brightback 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 Brightback button --><br>

6) Now that we're done updating the button itself we'll need to drop in the 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 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 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 

</script>
    <!-- Brightback precancel -->
    <script type="text/javascript">
      const processURL = "{{ subscription.id | subscription_cancel_url }}";
      const saveURL = window.location.href;            
      
      if (window.Brightback) {
        
        window.Brightback.handleData({
          app_id: "AaaaaaAaa1",
          email: "{{ customer.email }}",
          subscription_id: "{{ subscription.id }}",
          save_return_url: saveURL,
          cancel_confirmation_url: cancelURL,
          custom: {
              field value: "{{field_one}}"
             }
          });
        }
</script>

Note: Only the App_id, subscription_id, and email are required fields here. You can locate your 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.

Once you have integrated the 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 Retention app before doing so. Then return to your Recharge app and Preview the theme. 

Here you should be able to see the Retention cancel button that will route you to the Retention Cancel Experience. Once you have previewed the theme, you can publish it live via the Theme editor menu. 

Repurchase-Based Revenue Impact Reporting

One feature that we have not enabled yet for Recharge is our Repurchase Based Revenue Impact Reporting. This feature allows you to track the repurchase events that occur after a Retention session and attribute them to your Retention reports. This will give you additional granularity into how your Experiences and Offers are performing and which are driving the highest ROI. We will be releasing this feature in the near future, feel free to contact retention-support@chargebee.com to get on the waiting list!