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
plan: 'Pro',
mrr: 99,
stripeSubscriptionId: 'sub_xxx',
});
The email field is required. The plan, mrr, and stripeSubscriptionId fields are strongly recommended because they enable audience targeting conditions inside your flows. Without them, subscription-based targeting will not work.
⚠️ Important: Call rq('show') before processing the cancellation on your backend. If you cancel the subscription first, there is nothing for Churn.io to intercept.
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.