How to Build a Stripe Cancellation Flow

Minimum viable vs retention-aware paths

For step-by-step examples of what belongs in a retention-aware flow, see cancellation flow examples. This guide explains how to wire those steps to Stripe.

What Stripe handles

• Subscription lifecycle state (active, canceled, scheduled cancel via cancel_at_period_end, etc.)
• Invoice generation and payment collection rules
• Hosted Customer Portal UI (if you use the portal path)
• Webhook event delivery for subscription changes

What you build

• In-app intercept UI (or portal redirect/deep link entry)
• Reason capture and storage (your database, or portal configuration)
• Offer presentation and acceptance logic (custom path only)
• Server-side API calls that mutate subscriptions
• Webhook processing and idempotent event deduplication
• Internal outcome records for analytics

For a longer product-level comparison, see Stripe Customer Portal vs embedded cancellation flow.

Portal capabilities

Stripe’s Customer Portal can handle subscription cancellation when enabled in Dashboard settings. Per Stripe’s cancellation page documentation:

• Cancellation is enabled by default in the portal
• You can collect a cancellation reason from a fixed list (plus optional free text for “Other reason”)
• You can configure a retention coupon to deflect cancellations (one coupon for the portal cancellation flow)
• Cancellation timing in the portal depends on your portal configuration and billing mode — verify current behavior in Dashboard and Stripe’s cancellation page docs

To send a customer directly into the cancel flow, create a Billing Portal session with a deep link. Per Stripe’s portal deep links documentation, set flow_data[type]=subscription_cancel and pass the subscription ID:

curl https://api.stripe.com/v1/billing_portal/sessions \
  -u "$STRIPE_SECRET_KEY:" \
  -d customer="$CUSTOMER_ID" \
  --data-urlencode return_url="https://yourapp.com/account" \
  -d "flow_data[type]=subscription_cancel" \
  -d "flow_data[subscription_cancel][subscription]=$SUBSCRIPTION_ID"

Redirect the customer to the returned session url. The portal UI is hosted by Stripe — you cannot iframe it as a native in-app component.

Portal limitations relevant to custom flows

Portal behavior can change. Verify limitations against current Stripe Customer Portal documentation before relying on them in production.

When portal may be enough

• You have a simple subscription model
• Collecting a standard reason list is sufficient
• A single retention coupon deflection meets your save strategy
• You want the fastest path to compliant self-service cancel with minimal engineering

When a custom in-app flow may make sense

Again, what to show at each step is a product decision covered in Cluster #1. This guide covers how to connect your UI to Stripe.

• You need per-reason offer routing (pause vs coupon vs plan switch) before cancel
• You want a branded cancel experience inside your product
• You need session-level outcome tracking tied to your analytics model

Keep UX guidance short. For flow structure and anti-dark-pattern principles, see cancellation flow examples.

Custom flow

Store the reason in your database at flow time:

cancel_sessions
  id
  user_id
  stripe_subscription_id
  reason_code        -- e.g. "too_expensive"
  reason_comment     -- optional free text
  created_at

Link the session to the Stripe subscription ID so you can join flow data to billing state later.

For what to ask and how to phrase survey options, see cancellation survey questions. For reason taxonomies and playbooks, see SaaS cancellation reasons. This section covers only storage and wiring.

Portal flow

Configure reasons in Stripe Dashboard → Settings → Customer portal → Cancellations. Stripe documents the available reason list in the cancellation page guide. Reason data can appear on the subscription and via customer.subscription.updated webhooks — verify field availability in current Stripe API references for cancellation_details.

Apply a coupon to the subscription

Create coupons in Stripe, then apply them to an existing subscription via the Subscriptions API. Per Stripe’s coupons documentation, discounts are applied by creating a Discount on the subscription — commonly via a discounts parameter when creating or updating a subscription:

curl https://api.stripe.com/v1/subscriptions/$SUBSCRIPTION_ID \
  -u "$STRIPE_SECRET_KEY:" \
  -d "discounts[0][coupon]=$COUPON_ID"

Only call this after the customer accepts the offer in your UI. Verify parameter names against the current Subscriptions API reference before shipping.

Pause collection instead of cancel

To temporarily stop collecting payment while keeping the subscription active, use pause_collection on subscription update. Per Stripe’s pause payment collection documentation:

• The subscription remains active
• Invoices may still be created depending on pause_collection[behavior] (keep_as_draft, mark_uncollectible, or void)
• Payment collection resumes when you unset pause_collection or when resumes_at is reached

curl https://api.stripe.com/v1/subscriptions/$SUBSCRIPTION_ID \
  -u "$STRIPE_SECRET_KEY:" \
  -d "pause_collection[behavior]=keep_as_draft"

Pausing collection is not the same as canceling. Do not treat a paused subscription as churn in your internal analytics without explicit business rules.

Switch plan or downgrade

Update subscription items to a different price ID via subscriptions.update. Proration behavior depends on your subscription settings and update parameters — verify against Stripe’s update subscription documentation before implementing.

If the customer declines — proceed to cancel

After a fair offer is shown and declined, proceed to cancellation without adding unnecessary friction. UX principles for that handoff live in cancellation flow examples.

Period-end cancellation (cancel_at_period_end)

Schedule cancellation at the end of the current billing period:

curl https://api.stripe.com/v1/subscriptions/$SUBSCRIPTION_ID \
  -u "$STRIPE_SECRET_KEY:" \
  -d cancel_at_period_end=true

Per Stripe’s cancel subscriptions documentation:

• Setting cancel_at_period_end=true lets the subscription complete the period the customer already paid for
• Stripe sends customer.subscription.updated when the scheduled cancel is set
• When the period ends, Stripe sends customer.subscription.deleted
• Practical differences:
• Customer typically retains access through the paid period
• Billing relationship continues until period end
• You can reverse the scheduled cancel by setting cancel_at_period_end=false before the period ends (per Stripe docs)

Situations where teams may choose this: prepaid-period access policies, support workflows that need time to respond, or product models where immediate cutoff is not desired.

Immediate cancellation

Cancel the subscription right away via the Subscriptions API delete endpoint:

curl -X DELETE "https://api.stripe.com/v1/subscriptions/$SUBSCRIPTION_ID" \
  -u "$STRIPE_SECRET_KEY:"

Per Stripe’s cancel subscriptions documentation:

• By default, cancellation takes effect immediately
• After cancellation, the subscription is largely immutable except for metadata and cancellation_details
• Stripe sends customer.subscription.deleted
• Proration and refund behavior are configurable — verify options (prorate, invoice_now, etc.) in current API reference; do not assume defaults
• Practical differences:
• Access revocation can happen immediately (depending on how your app maps subscription status)
• No remaining paid period on the subscription
• Reversal requires creating a new subscription — you cannot “un-cancel” a deleted subscription

Situations where teams may choose this: explicit immediate-revoke policies, abuse or fraud handling, or regulatory requirements for prompt termination.

Choosing between period-end and immediate cancel

Portal path: Cancellation timing in Customer Portal is configured in Dashboard portal settings. Verify against Stripe’s cancellation page documentation.

Reversing a scheduled cancellation

To stop a pending period-end cancel before the billing period ends:

curl https://api.stripe.com/v1/subscriptions/$SUBSCRIPTION_ID \
  -u "$STRIPE_SECRET_KEY:" \
  -d cancel_at_period_end=false

Per Stripe, you cannot reactivate a subscription that has already been fully canceled.

Events that matter for cancellation

Per Stripe’s cancel subscriptions documentation:

For period-end cancels, subscription.updated fires when the cancel is scheduled; subscription.deleted fires when the subscription actually ends. If your app only listens for deleted, you may show incorrect access state during the remaining paid period.

Do not expand this guide into invoice.payment_failed or dunning handlers. Voluntary vs involuntary boundaries are covered in voluntary vs involuntary churn.

Webhook signature verification

Verify every webhook with your endpoint signing secret. Per Stripe’s webhooks documentation, use stripe.webhooks.constructEvent (or equivalent) with the raw request body, Stripe-Signature header, and your whsec_ secret. Reject requests that fail verification.

Return a 2xx response quickly. Do heavy processing asynchronously if needed to avoid timeouts and retries.

Idempotent webhook event processing / deduplication

Stripe may deliver the same event more than once. Your handler should deduplicate by event ID (e.g. store processed evt_ IDs) so retries do not:

• Revoke access twice
• Apply a save offer twice
• Write duplicate outcome rows

on webhook received:
  if event.id already in processed_events:
    return 200  -- already handled
  verify signature
  handle event
  insert event.id into processed_events
  return 200

This is webhook event deduplication — not the same as Stripe API idempotency keys on subscriptions.update or subscriptions.cancel. You may use both: idempotency keys for API retries from your server, and event-ID deduplication for webhook retries from Stripe.

Keeping internal state synchronized

Map Stripe subscription fields to app access:

Race condition: A customer may accept a coupon in your UI while a subscription.deleted webhook from an earlier action is still in flight. Serialize updates per subscription_id or use transactional checks against the latest Stripe object.

Store internal outcomes in your database — these are your fields, not Stripe’s:

• status — verify valid values in current Subscription object reference
• cancel_at_period_end — customer scheduled to leave but may still have access
• cancel_at — if using custom cancel dates (see Stripe cancel docs)
• saved — customer accepted an offer; subscription still active
• canceled_at_period_end — scheduled cancel confirmed
• canceled_immediate — subscription deleted immediately
• pending — flow started but Stripe state not yet confirmed

Recording outcomes for analytics

Log implementation events your analytics pipeline can consume later:

• reason_code, optional reason_comment
• offer_type_shown, offer_accepted (boolean)
• stripe_subscription_id, stripe_customer_id
• Subscription MRR snapshot at flow time (from your billing data)
• Final Stripe subscription status after the flow completes

For how to analyze this data — weighting reasons by MRR, offer performance, review cadence — see customer churn analysis. This guide stops at what to record during implementation.

For local webhook testing, use the Stripe CLI to forward events to your development endpoint.

ChurnIntel as one implementation option

If you prefer an embedded path over building everything in-house, ChurnIntel is one option for Stripe-billed SaaS:

• Embedded in-app widget — not a hosted no-code cancel page
• Stripe Connect with read/write access to apply coupons, pauses, plan changes, and cancellations on your behalf
• Voluntary cancellation scope only — not dunning or payment recovery
• ChurnIntel fits the custom-flow architecture described in this guide: intercept in your app, capture reason, apply retention actions in Stripe, record outcomes. Teams where Customer Portal is sufficient may not need it. Teams building fully custom flows may prefer their own implementation. See Stripe integration details for how Connect permissions map to the API patterns above.