Skip to main content

​
Widget Installation

The Windback cancellation widget captures cancel reasons and shows retention offers when customers try to cancel. It drops into any web app with a single script tag.

​
Script Tag Setup

Add the following script tag to your cancellation page or app layout: 
<script
  src="https://api.windbackai.com/widget.js"
  data-api-key="pub_your_public_key"
  async
></script>
Use your public key (pub_) for the widget. Never use your secret key in client-side code.

​
How It Works

1

Widget Loads

The script loads asynchronously and initializes the Windback widget. It does not block page rendering.
2

Customer Triggers Cancel

When the customer clicks your cancel button, call window.Windback.show() to open the widget modal.
3

Reason Collection

The widget presents a list of cancel reasons. The customer selects one and optionally adds free-text feedback.
4

Retention Offer

Based on the selected reason, the widget may show a targeted retention offer (discount, pause, downgrade) configured in your dashboard.
5

Data Sent to Windback

The cancel reason, feedback, and offer response are sent to Windback. A churn event is created and AI recovery begins.

​
Configuration Attributes

Set these attributes on the <script> tag to configure the widget:
AttributeTypeRequiredDefaultDescription
data-api-keystringYes---Your project’s public API key (pub_)
data-themestringNolightWidget theme: light or dark
data-positionstringNocenterModal position: center, bottom-right, bottom-left
<script
  src="https://api.windbackai.com/widget.js"
  data-api-key="pub_your_public_key"
  data-theme="dark"
  data-position="bottom-right"
  async
></script>

​
Triggering the Widget

The widget exposes a global window.Windback object. Call show() to open the cancellation modal: 
// Attach to your cancel button
document.getElementById("cancel-btn").addEventListener("click", () => {
  window.Windback.show();
});
You can also pass customer context: 
window.Windback.show({
  customerEmail: "jane@example.com",
  customerName: "Jane Smith",
  planName: "Team Pro",
  mrr: 4999,
});
Passing customer context enables more personalized retention offers and better recovery email targeting.

​
Allowed Origins

The widget validates the origin of the page it is loaded on. By default, all origins are allowed. To restrict which domains can use your public key:
  1. Go to Settings > API Keys
  2. Add allowed origins (e.g., https://app.yourcompany.com)
  3. The widget will refuse to load on unlisted origins
localhost origins are always allowed in development for convenience.

​
Graceful Degradation

The widget is designed to never break your cancellation flow:
ScenarioWidget BehaviorImpact on Your App
Script fails to loadWidget does not appearNone --- cancel flow proceeds normally
API key is invalidWidget shows error state, closesCancel flow proceeds
Network error during submissionWidget retries, then closes with warningCancel data may be lost, cancel flow proceeds
window.Windback is undefinedCalling show() is a no-opNone
Rate limitedWidget queues and retriesSlight delay, cancel flow proceeds
The widget will never prevent a customer from canceling. It is purely informational and incentive-based. Always ensure your cancel flow completes even if the widget fails.

​
Rate Limiting

The cancel flow widget is rate limited to 10 requests per 15 seconds per public key. This prevents abuse while allowing normal cancellation flows. If the rate limit is exceeded, the widget queues submissions and retries automatically.