Recharge

Chargebee Growth integrates directly with Recharge to enrich canceled sessions with billing data and to process cancellations and offers through the Recharge API.

About the Recharge integration

This integration supports two Recharge theme types, and the setup differs for each:

• Theme Engine like the Novum (Legacy theme) requires editing the Recharge Theme Editor and inserting the Chargebee Growth JavaScript snippet manually into your subscription template.
• Affinity theme uses a simpler, no-HTML path through the Recharge Customer Portal's built-in header and footer code injection.

Complete all applicable steps for your theme before going live.

Prerequisites

Before you begin, you need:

• A Chargebee Growth account with Settings access.
• A Recharge account with permission to generate API tokens and edit your storefront theme or Customer Portal.

Connect Recharge and Chargebee Growth with an API key

This step applies to both the Theme Engine and the Affinity theme.

1. In Recharge, go to Apps > API Tokens.

   Note

   Depending on your version of Recharge, you may see two API token types. If so, select Admin API Token.
   

2. Click Create an API token and assign the permission scopes required for all Chargebee Growth features to work.

   

3. Copy the generated token.

   

4. In Chargebee Growth, go to Settings > Integrations > Billing Integrations and paste the token into the Live Key field. Optionally, paste a separate test token into the Test Key field.

   We recommend linking your test key to a test billing site so you can test Manage Cancels and Manage Offers before going live.

5. Click Save. Once connected, fields are mapped automatically and the Manage the integration option becomes available.

   

Enable enrichment, cancel management, and offer management

After connecting the API key, configure the three core features of the Recharge integration.

Enrichment

Enrichment maps Recharge billing fields into Chargebee Growth automatically when you enable the integration. You can use these fields to define audiences for targeting and to personalize the cancel experience. To map fields beyond the standard set, use Custom Field Mapping.

The following standard fields are pulled 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.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

If you need a field that isn't listed here, contact Chargebee Growth support.

Once mapped, fields are available for page personalization and audience definition.

Cancel management

To configure cancel management, go to Settings > Setup > Billing system. Enrichment is enabled automatically. To also enable Manage Cancels, turn on the toggle.

When Manage Cancels is enabled, you can configure:

• Scope — cancel all subscriptions, or cancel individual subscriptions only.
• Timing — cancel immediately or at the end of the billing term.
• Level — set cancels at the App level (applies globally) or Page level (managed per page in the Page Settings tab of the page editor).

Align these settings to match how you handle cancellations in Recharge today.

Offer management

Once Manage Cancels is enabled, turn on Manage Offers in the same settings area.

Offer management connects offers in the Chargebee Growth Offer Library directly to Recharge, so they are processed through the API when a customer accepts an offer.

Before you configure a Discount offer in Chargebee Growth, create the coupon in Recharge first. The coupon code is then synced to the offer during setup.

The following offer types are supported natively:

To request additional offer types, contact Chargebee Growth support.

Prepaid subscriptions

Chargebee Growth supports Manage Cancels and Manage Offers for Recharge prepaid subscriptions, where the billing frequency differs from the shipment frequency. For example, a customer pays upfront for 6 months and receives a monthly shipment.

• Manage Cancels supports end-of-term cancellations only. Customers who cancel continue to receive the shipments they have already paid for and are not charged at the next renewal.
• Manage Offers supports discount and pause offers.

Install the cancel button in your Recharge theme

Follow the section that matches your Recharge theme.

Affinity theme

The Affinity theme uses the Recharge Customer Portal's code injection feature, so no HTML template editing is required.

1. In Recharge, go to Storefront > Customer Portal.

   

2. Select Embedded in platform storefront.

   Warning

   You must select Embedded in platform storefront. Choosing a different option results in an error.
   

3. Copy the snippet below, replace GROWTH_APP_ID with your Chargebee Growth app ID, and paste it into the Header or Footer section of the Customer Portal settings.

   <script type="text/javascript" src="https://app.retention.chargebee.com/js/current/brightback.js"></script>
   <script>
     document.addEventListener('Recharge::extension::cancellation_flow', event => {
       event.preventDefault();
       const { subscription, onSuccess, onError } = event.detail;
       const baseURL = `${window.location.origin}/tools/recurring/portal/${window.ReCharge.customer.hash}`;
       const urlParams = new URLSearchParams(window.location.search);
       const sessionToken = urlParams.get('token');
       window.Brightback.handleDataPromise({
         app_id: 'GROWTH_APP_ID',
         subscription_id: subscription.id,
         save_return_url: `${baseURL}/overview?token=${sessionToken}`,
         cancel_confirmation_url: `${baseURL}/overview?token=${sessionToken}`
       }).then(result => {
         if (result.valid) {
           window.location = result.url;
         } else {
           onError();
         }
       });
     });
   </script>
   

4. Click Save. Customers who click cancel are now redirected to the Chargebee Growth cancel experience.

Theme Engine

This option applies if you use a Recharge-hosted theme through the Theme Editor. The steps below use the Novum (Legacy) theme as an example.

1. In Recharge, go to Storefront > Theme Editor.

2. Duplicate the theme you want to edit. Alternatively, download the theme to edit locally and re-import it.

3. Click Edit code on the duplicated theme.

4. Go to the page that contains your cancel button or link. For the Novum (Legacy) theme, this is subscription.html.

5. Find the existing Recharge cancellation link. Comment it out or delete it entirely before publishing.

6. In its place, add the Chargebee Growth cancel button. Assign it the id of bb-cancel so Chargebee Growth knows which button launches the experience.

   <!-- Chargebee Growth 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.retention.chargebee.com/js/current/brightback.js?compiled=true"></script>
   <!-- End Chargebee Growth button -->
   

7. Add the precancel script below the button, in the <body> of subscription.html.

   Warning

   The precancel script must be placed in the <body> of the page, below the cancel button. Do not place it in the <head> tag or in a global site-wide script file.

   <!-- Chargebee Growth precancel -->
   <script type="text/javascript">
     const cancelURL = "{{ subscription_list_url }}";
     const saveURL = "{{ subscription.id | subscription_url }}";
     if (window.Brightback) {
       window.Brightback.handleData({
         app_id: "GROWTH_APP_ID",
         subscription_id: "{{ subscription.id }}",
         save_return_url: saveURL,
         cancel_confirmation_url: cancelURL
       });
     }
   </script>
   <!-- End Chargebee Growth precancel -->
   

   Note

   Only app_id and subscription_id are required. You can locate your app_id in the URL of your Chargebee Growth application. The save_return_url and cancel_confirmation_url control where customers land after they leave the cancel experience. For more information, see the Save and Cancel Return URL setup and the installation guide.

8. Confirm that you have updated your branding and published your targeting in Chargebee Growth before publishing.

9. In the Recharge Theme Editor, click Preview to verify that the cancel button launches the Chargebee Growth experience.

10. When confirmed, publish the theme from the Theme Editor menu.

Retained revenue impact reporting

Once the Recharge integration is live, you can measure the downstream financial impact of your retention efforts using retained revenue impact reporting. This includes repurchase metrics (first-time repurchase revenue, total and average repurchase orders, and cumulative retained revenue) and winback metrics (first winback rate, total and average winback orders, and cumulative winback revenue).

The integration also enables the retained revenue cohort report, which shows how deflections in Chargebee Growth drive downstream revenue over time.