Integrating Brightback with the Recharge Theme Engine
Brightback 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 Brightback, you will need to install the Brightback 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 + Brightback and get started saving customers!
We will break the integration down into three main steps:
- Connecting Recharge & Brightback via API keys
- Enabling Enrichment, Manage Cancels and Manage Offers
- Deploying the Brightback Cancel Button into your Recharge Theme
You will need to complete each of the ^ steps to get Brightback ready to launch with Recharge. We cover how to setup Brightback to optimize for Deflection in this article.
Connecting Recharge & Brightback via API Keys
The first step to get Brightback integrated with Recharge is to generate an API key in your Recharge App and connect it to Brightback. 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's to ensure all of the Brightback 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 Brightback 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.
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 Brightback 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 Brightback. These fields can then be used to define Audiences for Targeting and to personalize the Cancel Experience. Brightback will automatically connect with Recharge when you enable the integration and map a set of standard fields from Recharge into Brightback. You can add additional fields via our Custom Field mapping.
Here is a list of the standard fields Brightback 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 Note: If there is a field you are looking for that is not listed here, please contact email@example.com
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 pages 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 Brightback.
When you enable this, it will allow you to connect Offers in the Brightback 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 firstname.lastname@example.org
Discount Offers will pull in a coupon code that you generate in Recharge and sync it to the Offer in Brightback. 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 Brightback once it is created.
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 email@example.com.
Deploying the Brightback Cancel Button into your Recharge Theme Editor
The final step to get Brightback 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 Brightback 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 Brightback 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 Brightback which button should launch the Brightback experience.
6) Now that we're done updating the button itself we'll need to drop in the Brightback 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 Brightback 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 Brightback 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
Note: Only the App_id, subscription_id, and email are required fields here. You can locate your Brightback 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 Brightback, we cover that in more detail in this article.
Once you have integrated the Brightback 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 Brightback app before doing so. Then return to your Recharge app and Preview the theme.
Here you should be able to see the Brightback cancel button that will route you to the Brightback 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 Brightback session and attribute them up into your Brightback 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 firstname.lastname@example.org to get on the waiting list!