The Churn.io widget is a small piece of code you add to your website once. When one of your customers tries to cancel, it opens your retention flow as an overlay on top of your app — showing the right survey and offers without sending the customer to a separate page. This article walks you through installing the widget, connecting it to your account, and testing it before you go live.
You install the widget from the Embed page, on the Widget tab. There are three short steps: add the script, initialize it with your account key, and tell it when to open. You only ever install one widget — it automatically picks the correct flow for each customer.
Before you begin
For the widget to do its job, two things should be in place:
At least one live Widget-type flow. If you have no live flows, the widget has nothing to show. You can create and publish one from the Flows area.
A connected payment gateway. This is what lets Churn.io apply retention offers (discounts, pauses, free months, and so on) and process cancellations automatically. Connect it from the Integrations page.
The Widget tab shows a Status section that confirms both of these at a glance — a green check means you're ready, and an amber warning links you straight to where you can fix it.
Installing the widget
Step 1: Add the script tag
On the Widget tab, copy the script snippet and paste it once into your website's HTML, just before the closing </body> tag. This snippet never changes no matter how many flows you create, so you only add it once.
Step 2: Initialize with your account key
Copy the initialization snippet shown on the Widget tab — your real account key is already filled in for you. This snippet should run once when your page loads, after the script tag. It connects the widget to your Churn.io account.
💡 Where's my key?
Your account key is pre-filled in the initialization snippet on the Widget tab, so you can copy and paste without looking it up. If you don't see this step, you may be signed in with a view-only role — ask an owner or admin to grab the snippet for you.
Step 3: Open the flow when a customer cancels
Copy the third snippet and call it from wherever your cancellation happens — your cancel button's click handler, a route action, or wherever you currently process a cancellation request. This is what opens the retention flow as an overlay.
When you open the flow, you pass in details about the customer. These tell Churn.io which flow to show and let it personalise the offer:
Email — required. The customer's email address.
Plan — recommended. Your gateway's product identifier, used for audience targeting. It must match the value you selected in the flow's audience builder.
MRR — recommended. The customer's monthly recurring revenue, in dollars.
Subscription ID — recommended. Your gateway's subscription identifier. This is required for offers and cancellations to be applied automatically.
Custom attributes — optional. Any extra key-value details (for example company size or country) you want to target flows on.
⚠️ Pass the subscription details for automation
If you don't pass a subscription identifier, Churn.io can still show the flow and record the outcome, but it can't apply offers or cancel the subscription on your behalf — those actions need a real subscription to act on.
How flow targeting works
You install one widget, and it chooses the right flow for every customer on its own. Here's what happens behind the scenes:
When the widget loads, it fetches all of your live flows.
When you open the flow for a customer, it checks each flow's audience conditions against the customer details you passed in.
The first flow whose audience matches is the one shown to the customer.
If none match, your default flow is shown as a fallback. If you have no default flow, nothing is shown.
Because matching happens automatically, you don't need separate snippets for separate flows — just keep your flows and their audiences set up the way you want, and the widget does the rest.
Testing your flow before going live
The Widget tab includes a Test your flow console so you can preview the real experience right inside Churn.io, without touching your own site. Expand it and click Launch test flow — the widget opens using sample customer details so you can click through the survey and offers exactly as a customer would.
As you interact with the test flow, recent sessions appear in the log below it, each tagged with its outcome (for example saved, cancelled, or dismissed) along with the email and MRR. Use Stop to close the test and Clear log to reset the list.
💡 Nothing appears when you launch the test?
If the test closes immediately or shows a dismissed result, make sure you have at least one live Widget-type flow. The console only shows flows that are published and targeting the test customer.
Rotating your account key
If your account key is ever exposed or you simply want to issue a new one, you can rotate it from the initialization step on the Widget tab. Click Rotate API key, then Confirm rotate.
⚠️ Update your site after rotating
Rotating immediately invalidates the old key. Any widget already installed on your site will stop working until you copy the new initialization snippet and update your code.