The Churn.io widget is a lightweight JavaScript snippet that loads your cancel flow as a modal overlay on your site. No backend changes are required. This article explains how to install it and trigger it when a customer clicks your cancel button.
Step 1: Add the script tag
Paste this tag into your website's HTML, just before the closing </body> tag:
<script src="https://app.churn.io/widget.js"></script>
💡 Load it once globally. You only need this script tag once, typically in your main layout or app shell. It does not need to be on every page individually and loads asynchronously so it will not affect page speed.
Step 2: Initialise with your API key
Immediately after the script tag (or on page load), initialise the widget with your API key:
rq('init', { apiKey: 'pk_live_YOUR_API_KEY' });
Your API key is available from Flows > Embed > Widget tab in your Churn.io dashboard. It is pre-filled in the code snippet shown there.
Step 3: Trigger the widget on cancel
The widget does not open automatically. Call rq('show', ...) when the customer clicks your cancel button, passing their details so Churn.io can target the right flow and offers:
rq('show', {
// Required
email: '[email protected]',
// Recommended — used for audience targeting and offer application
plan: 'Pro',
mrr: 99,
stripeSubscriptionId: 'sub_xxx',
});
The email field is required. The plan, mrr, and stripeSubscriptionId fields are strongly recommended. The stripeSubscriptionId is required for Churn.io to apply retention offers directly to the subscription and to process cancellations in Stripe automatically.
⚠️ Important: Call rq('show') instead of processing the cancellation on your backend. Churn.io handles the Stripe cancellation automatically when the customer confirms. If you cancel the subscription before calling the widget, there is nothing for Churn.io to intercept.
What Churn.io handles automatically
When a stripeSubscriptionId is passed and your Stripe account is connected, Churn.io takes the following actions on your behalf:
Offer accepted: applies the offer to the Stripe subscription (coupon, trial extension, pause, or free month)
Cancellation confirmed: sets cancel_at_period_end: true on the subscription so it cancels at the end of the current billing period
The onCancelled() callback still fires after a confirmed cancellation, so you can use it to update your own UI or trigger any additional logic in your app.
Step 4: Test your installation
After installation, trigger your cancel button. The Churn.io widget should appear as a modal overlay. If it does not show, read My Widget Is Not Showing: Troubleshooting Guide for a step-by-step diagnosis.
💡 Get the exact snippet for your workspace. Your live API key is pre-filled in the code snippet at Flows > Embed > Widget. Copy it directly from there rather than typing it manually.
💬 Questions or concerns? Get help from our support specialists at Churn.io.