Installation Guide

KeepFlow adds a retention flow in front of your cancel button. Installation is two steps: add one script tag, then call KeepFlow.open() when a customer clicks “Cancel subscription”. Most teams are done in under 15 minutes.

Before you start

• A KeepFlow account with your Stripe account connected (done from the dashboard in one click).
• A project created in the dashboard — this gives you the API key used in the script tag below.
• Your app must know each customer's Stripe cus_… and sub_… IDs — you already store these if you bill with Stripe subscriptions.

Step 1: Add the script

Add this tag to any page where customers can cancel (your billing or account-settings page), or globally in your layout. Replace YOUR_API_KEY with the key from your project's Install tab.

<script src="https://keepflow.io/widget/keepflow.js" data-api-key="YOUR_API_KEY"></script>

The API key is publishable — it's safe in your page source. It only identifies your project and can't read data or touch subscriptions the visitor doesn't own. The script is ~7 KB, loads asynchronously (plain async and tag-manager installs are supported), and does nothing until you call it.

As soon as the script is live, your dashboard's Install tab flips to “Installation detected” so you can confirm this step worked before writing any code.

Step 2: Trigger the widget

Call KeepFlow.open() from your cancel button instead of canceling directly:

document.getElementById('cancel-button').addEventListener('click', () => {
  KeepFlow.open({
    // Required — from your own Stripe integration
    customerId: 'cus_xxx',        // the customer's Stripe ID
    subscriptionId: 'sub_xxx',    // the subscription being canceled

    // Optional — values for {{variables}} in your widget headline
    userData: { name: 'Ada', planName: 'Pro' },

    // Optional — where to send users if the widget can't load
    fallbackUrl: 'https://billing.stripe.com/p/session/...',

    onComplete: (result) => {
      if (result.status === 'saved') {
        // Customer accepted an offer — subscription unchanged or discounted
      } else {
        // Customer canceled (at period end) — update your UI
      }
    },
    onError: (error) => {
      // Widget failed — let your normal cancel flow proceed
    },
  });
});

What KeepFlow does with the result

• Customer accepts a discount — KeepFlow creates the coupon and applies it to the subscription via your connected Stripe account. Discounts never stack, and a customer who already used a save offer in the last 12 months won't get another.
• Customer accepts a pause — the subscription's collection is paused and auto-resumes after the configured number of months.
• Customer still cancels — the subscription is canceled at the end of the billing period (they keep what they paid for), and the reason + feedback land in your analytics.
• Anything fails — the widget shows a fail-safe screen so the customer can always complete their cancellation; you're notified via onError.

API reference

FAQ