Cancel Flow Widget
Embed LostChurn's cancel flow directly in your application to present retention offers and recover at-risk subscribers.
The Cancel Flow Widget embeds LostChurn's cancellation flow directly into your application. When a customer initiates cancellation, the widget intercepts the process and presents personalized retention offers, payment recovery prompts, or feedback surveys before the cancellation is finalized.
How It Works
Instead of canceling immediately, the widget guides the customer through a multi-step flow configured in your LostChurn dashboard under Cancel Flows:
The widget communicates with the LostChurn API to determine which cancel flow to present based on the customer's segment, subscription tier, and payment status.
Quick Start
React Component
import { LostChurnProvider, CancelFlowWidget } from "@lostchurn/react";
function AccountSettings() {
const handleCanceled = () => {
// Customer confirmed cancellation
router.push("/goodbye");
};
const handleRetained = (offer) => {
// Customer accepted a retention offer
toast.success(`Great! Your ${offer.name} has been applied.`);
};
return (
<LostChurnProvider publishableKey="lc_pub_your_key">
<CancelFlowWidget
customerId="cus_abc123"
subscriptionId="sub_xyz789"
onCanceled={handleCanceled}
onRetained={handleRetained}
/>
</LostChurnProvider>
);
}JavaScript SDK
import { LostChurn } from "@lostchurn/js";
const lc = new LostChurn("lc_pub_your_key");
document.getElementById("cancel-button").addEventListener("click", () => {
lc.openCancelFlow({
customerId: "cus_abc123",
subscriptionId: "sub_xyz789",
onCanceled: () => {
window.location.href = "/goodbye";
},
onRetained: (offer) => {
alert(`Your ${offer.name} has been applied.`);
},
onDismissed: () => {
// Customer closed the flow without completing it
},
});
});Script Tag
<button id="cancel-btn" data-lostchurn-cancel data-customer-id="cus_abc123" data-subscription-id="sub_xyz789">
Cancel Subscription
</button>
<script
src="https://cdn.lostchurn.com/widgets/v1/lostchurn.js"
data-publishable-key="lc_pub_your_key"
data-widget="cancel-flow"
async
></script>With the script tag integration, any element with the data-lostchurn-cancel attribute automatically opens the cancel flow when clicked.
Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
customerId | string | Required | The customer's payment processor ID |
subscriptionId | string | Required | The subscription to cancel |
flowId | string | Auto-selected | Specific cancel flow to use. If omitted, LostChurn selects the best flow based on customer segment |
mode | "modal" | "inline" | "redirect" | "modal" | How the cancel flow is presented |
theme | "light" | "dark" | "auto" | "auto" | Color scheme |
locale | string | Browser locale | Language for the cancel flow UI (e.g., "en", "es", "de") |
onCanceled | function | -- | Callback when cancellation is confirmed |
onRetained | function | -- | Callback when customer accepts a retention offer |
onDismissed | function | -- | Callback when customer closes the flow without completing |
onStepChange | function | -- | Callback on each step transition, receives step name and index |
onError | function | -- | Callback when an error occurs during the flow |
Display Modes
Modal (Default)
The cancel flow opens as a centered modal overlay on top of your page. The customer can close the modal by clicking outside it or pressing Escape.
<CancelFlowWidget
customerId="cus_abc123"
subscriptionId="sub_xyz789"
mode="modal"
/>Inline
The cancel flow renders directly in your page layout, replacing the cancel button or embedding within a settings panel.
<CancelFlowWidget
customerId="cus_abc123"
subscriptionId="sub_xyz789"
mode="inline"
container="#cancel-flow-container"
/>Redirect
The customer is redirected to a hosted LostChurn page for the cancel flow, then redirected back to your site when complete.
<CancelFlowWidget
customerId="cus_abc123"
subscriptionId="sub_xyz789"
mode="redirect"
returnUrl="https://yourapp.com/account/settings"
/>Cancel Flow Steps
The cancel flow consists of steps configured in your LostChurn dashboard. Common steps include:
| Step Type | Description |
|---|---|
| Reason Survey | Asks the customer why they want to cancel. Responses feed into your analytics |
| Retention Offer | Presents a discount, plan downgrade, pause, or extension |
| Payment Recovery | If the customer has a failed payment, prompts them to update their payment method |
| Feedback | Open-ended text field for additional feedback |
| Confirmation | Final step where the customer confirms or abandons cancellation |
You configure the steps, offers, and messaging for each cancel flow in the LostChurn dashboard under Cancel Flows > Builder. See Building Cancel Flows for a detailed guide.
Outcome Handling
The widget returns structured data about the outcome so you can take the appropriate action in your application.
Cancellation Confirmed
onCanceled: (result) => {
// result.reason — selected cancellation reason
// result.feedback — optional free-text feedback
// result.canceledAt — ISO timestamp
// result.subscriptionId — the canceled subscription
// You should now cancel the subscription in your system
await cancelSubscription(result.subscriptionId);
}Customer Retained
onRetained: (offer) => {
// offer.type — "discount", "pause", "downgrade", "extension"
// offer.name — human-readable offer name
// offer.appliedAt — ISO timestamp
// offer.details — offer-specific details (e.g., discount percentage)
// The offer has already been applied by LostChurn
// You may want to update your UI or show a confirmation
}When onCanceled fires, LostChurn does not automatically cancel the subscription in your payment processor. You are responsible for executing the cancellation in your backend. This gives you full control over the cancellation timing (immediate vs. end of period) and any cleanup logic.
Next Steps
- Building Cancel Flows -- configure the steps and offers in the cancel flow
- Recovery Bar -- show a payment failure banner
- Customization -- theme the widget to match your brand