Scope

How to configure Stripe Billing Integration in Chargebee Retention?

Stripe billing integration with Chargebee Retention

Summary

Connect the Stripe integration in just a few simple steps, starting in the Settings tab located in the lower left of the navigation bar of the Chargebee Retention application. View the full step-by-step guide to connecting Stripe to Chargebee Retention. Once Stripe is connected, you will need to activate the core use cases of the integration in the Settings Page under Setup.

Solution

Chargebee Retention's native integration with Stripe makes it easy for you to retain subscribers and revenue by reducing voluntary churn. By connecting Chargebee Retention to Stripe, you will be able to enable our four main billing integration use cases: 

• Attribution - This validates a Chargebee Retention Save event by confirming a subscription is still valid when the Save event fires, then retrieving revenue values to calculate and apply the revenue to your Chargebee Retention dashboards and reports

• Enrichment - map fields from the Stripe subscription record to personalize your experiences, build custom Audiences for user targeting purposes   

• Manage offers - directly pause, discount, extend, and update a subscription in Stripe based on Stripe Subscription ID when a customer accepts a Chargebee Retention offer

• Manage cancels - directly cancel a subscription in Stripe when a user completes the cancel request, which can be configured to: include all active subscriptions on a Stripe Customer record, invoice users immediately for all outstanding charges, or Prorate the subscription. 

These use cases are core to Chargebee Retention and allow you to perform some of the key elements of your cancel flow, including:

• Update a subscription directly in Stripe, following the valid submission of a cancel request or Offer from the Chargebee Retention Page.

• Pull subscription data from Stripe into Chargebee Retention to enrich the profile of your customer for use in targeting custom audiences, personalizing the cancel experience, and segmenting data records to build richer save and churn reports.

• Validate that customers are still paying when Chargebee Retention: Classifies a customer as saved, by looking up the subscriber by their Stripe Account ID and confirming their payment status.

• Calculate the dollar amount in revenue that is saved (or churned): Per session, which is a customer that shows intent to cancel by being directed to the Chargebee Retention cancel page.

Connecting Chargebee Retention to Stripe

In order for the Stripe integration to work, you must first connect your Stripe account to Chargebee Retention by creating a restricted API key, then you need the unique subscription reference ID of the canceller. This unique ID is captured dynamically from the Chargebee Retention.js code snippet when the user first initiates a session by clicking to cancel. An example of the minimum required request body is below. Please be sure to review the documentation on how to install the Chargebee Retention javascript snippet to learn about additional properties that can be sent.

{
  "app_id": "BRIGHTBACK_APP_ID",        
  "subscription_id": "sub_K1Vhej7WAk7k7Z",     
}

Connect the Stripe integration in just a few simple steps, starting in the Settings tab located in the lower left of the navigation bar of the Chargebee Retention application. View the full step-by-step guide to connecting Stripe to Chargebee Retention. 

Note: To enable Stripe to process the cancellation and include enrichment data you must create an API write key with the following scopes

Activating the Subscription

Once Stripe is connected, you will need to activate the core use cases of the integration in the Settings Page under Setup.

Enriching your subscription profile  

Once Stripe is connected, you can leverage Chargebee Retention's Enrichment feature to reduce the engineering time and effort needed to install the Chargebee Retention.js snippet. With the integration enabled, Chargebee Retention will use the StripeID to lookup and key subscriber data in Stripe (such as first purchase date or billing frequency) and sync it back into Chargebee Retention to map to Chargebee Retention fields using Field Mappings located under 'Settings' (read below).  

Note: If you do not send a valid subscription id or have a valid connection to Stripe, Chargebee Retention will not be able to pull subscription information at load time. In this case, your subscriber would be routed to your control or default cancel experience, and any dynamic field data used for personalization will default to the fallback variables.

Syncing and mapping Stripe fields into Chargebee Retention

Before you can successfully map Stripe data into Chargebee Retention, you must first ensure that you are capturing the Stripe subscription ID via the Chargebee Retention.js, and have mapped this field to the Subscription ID in the field mappings page. 

Once successfully connected to Stripe, navigate to 'Field mappings' under Settings, to start mapping. For each Chargebee Retention field that you will map to, you must first specify the field data type (e.g. text, date, decimal, email, URL), then select the source field in Stripe, visible under the Stripe source in the menu dropdown. 

Go ahead and map as many fields as you would like. Mapped fields can be used to personalize the cancel page, target the cancel experience/offers, and in reporting via the customer's page. 

Example Stripe payload

{
  "subscription.customer.email": "[email protected]",
  "subscription.plan.interval": "year",
  "subscription.plan.id": "premium_snack_pack",
  "subscription.id": "sub_abcdefghijk",
  "subscription.current_period_end": 946684800,
  "subscription.plan.billing_scheme": "per_unit",
  "subscription.customer.created": 946684800,
  "subscription.trial_start_date": 946684800,
  "subscription.plan.amount_decimal": 99000,
  "subscription.trial_end_date": 946684800,
  "subscription.product.name": "Premium Snack Pack",
  "subscription.start_date": 946684800,
  "subscription.customer.id": "cus_abcdefghijk",
  "subscription.plan.interval_count": 1,
  "subscription.product.id": "prod_abcdefghijk",
  "subscription.created": 946684800,
  "subscription.current_period_start": 946684800
}

Missing a field? Please contact [email protected] and we'll look into adding it. 

Processing Cancels in Stripe

When a user completes a cancel on the Chargebee Retention page, we will update Stripe to mark the subscription as canceled. This process works as follows: 

• Cancel the matching Stripe Subscription ID via the Stripe integration. When a customer submits a valid cancellation request via your Chargebee Retention page, Chargebee Retention cancels the matching Stripe Subscription ID. Confirm by navigating to Customers/Subscriptions in Stripe, and confirming that the customers' subscription is pending cancellation. 

You can choose how to apply the cancel in Stripe under the Setup tab for the integration. 

Select the options that match how you currently handle cancellations in Stripe and hit Save & Close. 

Processing Offers In Stripe

You also can process Offer updates directly to Stripe subscriptions. We support the ability for you to map Discounts, Pauses, Extensions, and Plan Changes directly to Stripe subscriptions. When the user selects one of these offers in the cancel flow, we will apply it directly to the corresponding subscription in Stripe. To get started with Offer Management, go ahead and enable this toggle on the Settings page. 

Start off by creating a new coupon in your Stripe account. 

Next, create a 'Discount' type offer in Chargebee Retention, where you will finalize the offer content, button copy, and define where the offer appears on your Chargebee Retention page (Placement).

Finally, you will use the Billing sidebar to browse and select the billing coupon created above in Stripe, which is applied to your customers' subscriptions when they accept this offer.

• Pause a Stripe subscription: To automatically pause a Stripe subscription, you will first create a New Pause offer in Chargebee Retention, per the steps above, this time selecting the Pause offer type. However, when configuring billing, you will now have the option to define a pause duration, based on the pause Duration and Interval (below). A Chargebee Retention Pause is equivalent to "Void" behavior (i.e. no service) applied via the Stripe API. An example here might be to test a 2-month pause of your product/service, targeting customers who do not intend to use it for a period of time (e.g. are going on vacation or the project has been delayed).  

• Change a Stripe Plan: to automatically change a Stripe subscription, create a new 'Plan Change' offer in Chargebee Retention, per the steps above. When configuring billing, simply select a plan from the available list in the dropdown, which will be automatically updated upon the offer user accepts this offer type.    

• Extend a Stripe Plan: To automatically extend a Stripe subscription, create a new 'Extension' offer type in Chargebee Retention, per the steps above. When configuring billing, simply select the Duration and the Interval from the available list in the Extension dropdown. 

Note: This is similar to the Pause offer above, however, a Chargebee Retention free extension is equivalent to mark_uncollectible behavior in the Stripe API (provide the service for free). An example here might be to offer an extended trial of your product/service, such that your customer still retains full use and control over their account.

Validate Saves and Attribute Revenue with Attribution 

The Attribution integration enables Chargebee Retention to cross-check your billing system to validate any Chargebee Retention Saved or Watch List customers haven't canceled or let their accounts lapse in other ways beyond Chargebee Retention, and calculate the dollar amount in revenue saved (or lost) per customer that hits your Chargebee Retention Page. Once you've enabled the Stripe Attribution integration, you'll see a Revenue data card start to populate in the Chargebee Retention Settings menu showing you the last sync, and how many accounts have matched to a customer in Stripe.

Processing customized Cancels and Saves in Stripe

If your Stripe Billing account is not configured properly, or you don't use Stripe to manage subscriptions, you may alternatively automatically cancel or modify your subscriptions using Chargebee Retention's webhooks or pass-through URLs (which requires some engineering to set up), as follows:  

• Chargebee Retention Webhooks - When a customer cancels or accepts an offer (e.g. 1 free month, pause, etc.), then Chargebee Retention's Webhook event URL triggers an action in Stripe. Note: you would need to have already set up a Coupon in Stripe, then the Chargebee Retention webhook will apply the coupon to the actual customer. 

• Pass Thru URLs -  When a customer cancels or accepts an offer (e.g. 1 free month) then Chargebee Retention calls a URL, that can trigger an in-biling action (e.g. https://netflix.com/free-month?customer_id=12345&interval=1). Passive deflects (scenario 3, above) do not need any subscription modifications in Stripe, and the canceler is redirected back to a returning URL specified in the Chargebee Retention.js snippet ('save_return_url').

Need a Chargebee Retention developer sandbox for testing the integration with a Stripe dev account? Please contact [email protected] or your account manager, who can promptly set up your developer account.    

Install your snippet and send cancel sessions to Chargebee Retention

The final step to using our Stripe integration is to send cancel sessions to Chargebee Retention with the unique subscription id populated dynamically in the snippet. Below is an example of the minimum properties you would need to send in order to create unique cancel sessions. 

<a id="bb-cancel" href="/fallback">Cancel</a>
<script
  type="text/javascript"
  src="https://app.brightback.com/js/current/?compiled=true"
></script>
<script type="text/javascript">
  if (window.Brightback) {
    window.Brightback.handleData({
      app_id: "APP_ID", //your Brightback APP_ID
      subscription_id: "sub_KA14zABcgS4fhQ", //dynamically populated Stripe subscription id
    });
  }
</script

You of course can send other properties like usage activity in a custom object for personalization and targeting.  For more info on that or other installation options check out our full article on installing Chargebee Retention.

Related Articles

Enrichment (Retention) with Chargebee Billing, Stripe, Recurly

Connecting the Stripe integration - Chargebee Retention