@churnback/sdk

Reduce churn with intelligent cancel flows and dunning banners. Drop-in JavaScript SDK for any web app.

Install

npm install @churnback/sdk

Quick Start

import ChurnBackClient from "@churnback/sdk";

const churnback = new ChurnBackClient({
  apiKey: "your-api-key",
});

// Show a cancel flow when a user clicks "Cancel Subscription"
document.getElementById("cancel-btn").addEventListener("click", () => {
  churnback.triggerCancelFlow({
    stripeCustomerId: "cus_xxx",
    stripeSubscriptionId: "sub_xxx",
    onComplete: (result) => {
      if (result.action === "saved") {
        console.log("Customer saved!");
      } else if (result.action === "cancelled") {
        console.log("Customer cancelled:", result.reason);
      }
    },
    onError: (error) => {
      console.error("Cancel flow failed:", error.message);
      // Re-enable the cancel button, show a fallback, etc.
    },
  });
});

API

new ChurnBackClient(config)

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | Yes | Your ChurnBack API key | | apiBaseUrl | string | No | Custom API base URL (defaults to https://churnback.ai/api/sdk) |

triggerCancelFlow(options)

Opens an interactive cancel flow modal with surveys, offers, and confirmation steps.

| Option | Type | Required | Description | |--------|------|----------|-------------| | stripeCustomerId | string | Yes | Stripe customer ID | | stripeSubscriptionId | string | Yes | Stripe subscription ID | | stripePriceId | string | No | Stripe price ID for targeted offers | | onComplete | function | No | Callback with { action, reason, comment, offerAccepted } | | onDismiss | function | No | Called when the user closes the modal | | onError | function | No | Called with an Error if the flow fails to load (network error, invalid IDs, etc.). Prevents the promise from rejecting. |

The action in the result is one of: "saved", "cancelled", or "dismissed".

checkDunning(options)

Checks if a customer has a failed payment.

const result = await churnback.checkDunning({
  stripeCustomerId: "cus_xxx",
});

mountDunningBanner(options)

Renders a payment failure banner inside a target element.

churnback.mountDunningBanner({
  stripeCustomerId: "cus_xxx",
  targetElement: "#billing-section", // CSS selector or HTMLElement
});

destroy()

Cleans up all modals and banners.

churnback.destroy();

Script Tag Usage

For apps that don't use a bundler:

<script src="https://unpkg.com/@churnback/sdk/dist/index.global.js"></script>
<script>
  const churnback = new ChurnBack({ apiKey: "your-api-key" });
</script>

License

MIT