Cancellation Flows

This page explains the concepts. To turn it on step by step, follow the cancel-flows setup guide.

Guided Cancellation Experiences

Cancellation flows create guided, multi-step experiences when customers attempt to cancel. Instead of a single “Cancel” button, you present a structured flow that collects feedback, offers retention incentives, and requires explicit confirmation.

Multi-step sequences — Survey, offer, and confirmation steps in any order
Retention offers — Discounts, trial extensions, pauses, and custom offers
Cooldown periods — Prevent repeated cancellation attempts within a time window
Session tracking — Track every cancellation attempt and its outcome
Retention analytics — Measure retention rates and top cancellation reasons

Cancellation flows integrate with Churn Prediction to proactively engage at-risk customers before they reach the cancel button.

How It Works

Create a Cancellation Flow

curl -X POST https://api.recurso.dev/v1/cancel-flows \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard Cancel Flow",
    "cooldown_hours": 48,
    "steps": [
      { "type": "survey", "title": "We are sorry to see you go", "required": true },
      { "type": "offer", "title": "Before you go...", "required": false,
        "offer": { "type": "discount", "value": 50, "duration_days": 90 } },
      { "type": "confirmation", "title": "Confirm cancellation", "required": true }
    ]
  }'

Flow Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Flow name
`description`	string	No	Flow description
`cooldown_hours`	integer	No	Hours before a customer can start a new session
`steps`	array	Yes	Ordered list of flow steps

Step Types

Type	Purpose	Key Fields
`survey`	Collect cancellation reason and feedback	`title`, `description`, `required`
`offer`	Present a retention offer	`title`, `description`, `required`, `offer`
`confirmation`	Require explicit cancellation confirmation	`title`, `description`, `required`

Retention Offers

Offer Type	Value Meaning	Example
`discount`	Percentage off subscription price	`value: 50` = 50% off
`extension`	Free days added to current period	`value: 30` = 30 extra days
`pause`	Subscription paused for N days	`value: 60` = 2-month pause
`custom`	Custom offer described in `description`	`value: 0`, custom description

// Offer structure
{
  type: 'discount',       // discount | extension | pause | custom
  value: 50,              // Percentage, days, or 0 for custom
  duration_days: 90,      // How long the offer applies
  description: '50% off for 3 months'
}

Session Lifecycle

Start a Session

curl -X POST https://api.recurso.dev/v1/cancel-flows/sessions/start \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_abc123",
    "subscription_id": "sub_xyz789",
    "flow_id": "cf_flow_001"
  }'

If the customer has an active cooldown from a previous session, starting a new session returns a 409 Conflict with the cooldown expiry time.

Submit a Step

curl -X POST https://api.recurso.dev/v1/cancel-flows/sessions/cfs_session_001/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "step_id": "step_survey_001",
    "response": { "reason": "too_expensive" },
    "accepted_offer": false
  }'

Session Statuses

Status	Description
`in_progress`	Customer is stepping through the flow
`completed`	Customer confirmed cancellation
`cancelled`	Customer abandoned the flow
`retained`	Customer accepted a retention offer

Get Session

curl -X GET https://api.recurso.dev/v1/cancel-flows/sessions/cfs_session_001 \
  -H "Authorization: Bearer $API_KEY"

Cooldown Periods

The cooldown_hours parameter prevents a customer from starting a new session too frequently, giving retention offers time to take effect.

// POST /v1/cancel-flows — a flow is a name + ordered steps.
// cooldown is in DAYS; steps carry a step_type and a free-form config.
const res = await fetch(`${BASE_URL}/v1/cancel-flows`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'With Cooldown',
    is_default: true,
    cooldown_days: 3,
    steps: [
      { step_order: 1, step_type: 'survey', config: { title: 'Why are you leaving?' } },
      { step_order: 2, step_type: 'offer',  config: { coupon_code: 'SAVE30' } },
      { step_order: 3, step_type: 'confirm', config: { behavior: 'end_of_period' } },
    ],
  }),
});
const flow = (await res.json()).data;

Manage Flows

// GET    /v1/cancel-flows                     list flows
// PUT    /v1/cancel-flows/{id}                update a flow (name, is_default, cooldown_days)
// POST   /v1/cancel-flows/{id}/steps          add a step
// PUT    /v1/cancel-flows/steps/{id}          update a step
// DELETE /v1/cancel-flows/steps/{id}          remove a step
//
// A customer-facing run is a session:
// POST /v1/cancel-flows/sessions/start { customer_id, subscription_id }
// POST /v1/cancel-flows/sessions/{id}/submit  advance a step
// GET  /v1/cancel-flows/stats                 saves vs. cancels

Retention Analytics

curl -X GET https://api.recurso.dev/v1/cancel-flows/stats \
  -H "Authorization: Bearer $API_KEY"

Field	Type	Description
`total_sessions`	integer	Total cancellation sessions started
`completed_sessions`	integer	Sessions where the customer confirmed cancellation
`retained_customers`	integer	Customers who accepted a retention offer
`retention_rate`	float	Ratio of retained to total sessions
`top_reasons`	array	Most common cancellation reasons from surveys

Webhooks

Event	Description
`cancel_flow.session_started`	Customer started a cancellation flow
`cancel_flow.step_submitted`	Customer submitted a step response
`cancel_flow.offer_accepted`	Customer accepted a retention offer
`cancel_flow.session_completed`	Customer confirmed cancellation
`cancel_flow.session_abandoned`	Customer left without completing

Best Practices

Keep It Short

Limit flows to 2-3 steps. Long flows frustrate customers and damage brand trust.

Make Offers Relevant

Use churn prediction risk factors to tailor offers. Price-sensitive customers need discounts; underutilizers need onboarding.

Set Reasonable Cooldowns

24-72 hours is typical. Too short and you spam; too long and you trap customers.

Analyze Top Reasons

Review cancellation reasons regularly to drive product decisions and reduce churn at the source.

What happens when a customer accepts an offer?

The session status changes to retained, and the offer is applied to the subscription automatically. For discount offers, a coupon is created and applied for the specified duration.

Can I have multiple active flows?

Yes. Create multiple flows and specify which to use when starting a session. If no flow_id is provided, the default active flow is used.

Are survey responses stored?

Yes. All step responses are stored in the session’s responses field as JSON keyed by step ID, retrievable via the session API.

Get Started

Migrate to Recurso

Core Concepts

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

Guided Cancellation Experiences

How It Works

Create a Cancellation Flow

Flow Parameters

Step Types

Retention Offers

Session Lifecycle

Start a Session

Submit a Step

Session Statuses

Get Session

Cooldown Periods

Manage Flows

Retention Analytics

Webhooks

Best Practices

Keep It Short

Make Offers Relevant

Set Reasonable Cooldowns

Analyze Top Reasons

​Guided Cancellation Experiences

​How It Works

​Create a Cancellation Flow

​Flow Parameters

​Step Types

​Retention Offers

​Session Lifecycle

​Start a Session

​Submit a Step

​Session Statuses

​Get Session

​Cooldown Periods

​Manage Flows

​Retention Analytics

​Webhooks

​Best Practices

Keep It Short

Make Offers Relevant

Set Reasonable Cooldowns

Analyze Top Reasons

Guided Cancellation Experiences

How It Works

Create a Cancellation Flow

Flow Parameters

Step Types

Retention Offers

Session Lifecycle

Start a Session

Submit a Step

Session Statuses

Get Session

Cooldown Periods

Manage Flows

Retention Analytics

Webhooks

Best Practices