Migrate Stripe Subscription to One-Time Billing [2026]

Migrating a Stripe subscription business to one-time payments is a four-step procedure: (1) pick the cancellation mode per cohort (cancel_at_period_end: true for grandfathered access vs immediate cancel with prorate: true for refund-on-exit), (2) make the webhook handler dual-mode so legacy subscription events and new checkout.session.completed events both route correctly during the transition window, (3) tie access revocation to the actual Stripe state transition rather than the moment you flip the flag, and (4) send customer comms anchored to the specific webhook event that fired each state change. The trap that ambushes most founders is the timing gap between customer.subscription.updated (fires when you set the flag) and customer.subscription.deleted (fires weeks later when the period ends) [1][3].

This is the cluster 4.3 implementation deep-dive on the migration path itself. The billing architecture pillar covers whether to migrate (the 6 mechanical Stripe differences and what each costs to maintain), and the comparison page is the side-by-side decision framework. This post starts after the decision is made and walks the actual API procedure, the dual-mode handler logic, and the five access-revocation failure modes that show up in production.

TL;DR:

• The two-event timing distinction is the trap. Setting cancel_at_period_end: true fires customer.subscription.updated instantly. The actual customer.subscription.deleted fires only when the billing period ends, which can be weeks or months later [3]. A handler that revokes access on the wrong event either revokes too early or weeks late.
• Two cancellation modes, two business policies. cancel_at_period_end: true keeps the customer on the existing subscription until renewal, no refund. Immediate cancel with prorate: true plus invoice_now: true credits the unused time and ends access today [1][2].
• Dual-mode webhooks during the transition window. Both subscription lifecycle events and one-time checkout.session.completed events fire for the same customer during migration. The handler discriminates on session.mode === 'payment' for new one-time flows and keeps the customer.subscription.* cases live for legacy customers.
• Access revocation must read the subscription state, not the flag. A cancel_at_period_end: true subscription still has status === 'active' until the period actually ends. Revoke on status change, not on the flag.
• Customer comms map 1:1 to webhook events. The cancellation-scheduled email fires from customer.subscription.updated. The access-revoked email fires from customer.subscription.deleted. The migration-complete email fires from checkout.session.completed on the new one-time purchase.

Table of contents

• Why is migrating Stripe subscriptions to one-time payments harder than it looks?
• Which Stripe cancellation mode should you use: cancel_at_period_end or immediate?
• How do you make the webhook handler dual-mode during the migration window?
• How do you prevent the access-revocation race condition?
• What should your customer-comms templates say at each Stripe state transition?
• What are the 5 failure modes that ambush founders mid-migration?
• When does a Stripe migration mean you should rethink the architecture?

Why is migrating Stripe subscriptions to one-time payments harder than it looks?

The migration looks like "cancel subscriptions, sell one-time, done." It is not. The trap is timing: setting cancel_at_period_end: true does not cancel the subscription today, it schedules cancellation at the end of the current billing period. Stripe fires customer.subscription.updated at the moment you set the flag and fires customer.subscription.deleted only when the period actually ends [3]. Between those two events, the subscription is still status: 'active', still entitled, still charging if a renewal happens to land first.

That gap is where access-revocation logic goes wrong. A handler that revokes access on customer.subscription.updated (treating the flag flip as the cancellation) locks paying customers out weeks early. A handler that ignores the flag and only revokes on customer.subscription.deleted is correct, but it has to keep the subscription "active and entitled" in the application's mental model for the whole grace period, which most ad-hoc handlers do not. The result, repeatedly, is customers who paid for an annual subscription getting access cut off two minutes after they clicked a cancellation confirmation.

The second layer is dual-event traffic. While legacy customers are still draining out of their subscription periods, new customers are flowing through mode: 'payment' Checkout. Stripe sends customer.subscription.deleted for the former and checkout.session.completed (with session.mode === 'payment') for the latter. Both events hit the same webhook endpoint. A handler that was written for one mode does not gracefully accept the other; the cases either fall through silently or get processed by the wrong branch. The migration window is the period (often 6 to 12 months for annual subscriptions) where both event families are live simultaneously.

The third layer is comms. Subscription customers expect a confirmation when they cancel. They expect a reminder before access ends. They expect a final receipt when access is revoked. Each of those emails fires from a different Stripe event, and the wrong event-to-email mapping produces either notification spam (sending the cancellation email twice, once on the flag and once on the actual deletion) or notification silence (the customer never hears that access was revoked because the handler routed the email off the wrong event). The fix is to map each email template to one specific webhook trigger and to do that mapping explicitly, not by inferring "what state are we in" from the application database.

Which Stripe cancellation mode should you use: cancel_at_period_end or immediate?

Two cancellation modes, two distinct business policies. Pick per cohort, not for the whole migration.

Mode A: schedule cancellation at period end (most common).

This is the right default for an annual or monthly subscription where the customer has already paid for the current period. The customer keeps access until renewal, no refund is issued, and the subscription quietly expires on the renewal date. Set it via the Update Subscription endpoint:

// actions/billing-migration.ts
'use server'

import { getStripe } from '@/lib/stripe/client'
import { createAdminClient, getUser } from '@/lib/supabase/server'

export async function scheduleCancellationAtPeriodEnd(subscriptionId: string) {
  const user = await getUser()
  if (!user) return { error: 'Not authenticated' }

  // Authorization: confirm this subscription belongs to the caller
  const admin = createAdminClient()
  const { data: sub } = await admin
    .from('subscriptions')
    .select('user_id')
    .eq('id', subscriptionId)
    .single()
  if (!sub || sub.user_id !== user.id) return { error: 'Not authorized' }

  // Stripe: flip the flag, do not delete yet
  const updated = await getStripe().subscriptions.update(subscriptionId, {
    cancel_at_period_end: true,
  })

  return { success: true, periodEnd: updated.current_period_end }
}

Per Stripe's API reference, cancel_at_period_end is documented as: "Indicate whether this subscription should cancel at the end of the current period (current_period_end). Defaults to false." [1] Setting it to true fires customer.subscription.updated immediately and customer.subscription.deleted when the period actually ends [3].

Mode B: cancel immediately with prorated refund.

This is the right call when you are pulling a problem cohort off the platform fast (e.g., the subscription tier was misconfigured, or you want to give early-adopter refunds as part of the goodwill of migrating). Use the Cancel Subscription endpoint with prorate: true and invoice_now: true so Stripe generates a final invoice that credits the unused time:

export async function cancelImmediatelyWithRefund(subscriptionId: string) {
  const user = await getUser()
  if (!user) return { error: 'Not authenticated' }

  const admin = createAdminClient()
  const { data: sub } = await admin
    .from('subscriptions')
    .select('user_id')
    .eq('id', subscriptionId)
    .single()
  if (!sub || sub.user_id !== user.id) return { error: 'Not authorized' }

  // Stripe: cancel immediately, generate proration credit, invoice now
  await getStripe().subscriptions.cancel(subscriptionId, {
    prorate: true,
    invoice_now: true,
  })

  return { success: true }
}

Stripe's docs are explicit on the flag semantics: prorate "will generate a proration invoice item that credits remaining unused time until the subscription period end" and invoice_now "will generate a final invoice that invoices for any un-invoiced metered usage and new/pending proration invoice items." [2] Both default to false, which means a plain subscriptions.cancel(id) cancels immediately with no refund and no final invoice.

Two notes that matter. First: once a subscription is actually canceled (Mode A after the period ends, or Mode B immediately), it cannot be reactivated. Stripe is explicit: "You can't reactivate a canceled subscription." [3] The only reversal mechanism is for Mode A before the period ends, where you can set cancel_at_period_end: false to stop the pending cancellation. Plan for this irreversibility when you communicate with customers. Second: customers in Mode A typically need a small grace window where they can still sign up for the new one-time product without overlapping charges. The dual-mode handler in the next section is what makes that possible.

How do you make the webhook handler dual-mode during the migration window?

The dual-mode handler keeps the subscription lifecycle cases live for legacy customers AND adds the one-time checkout.session.completed path for new customers. Discriminate on session.mode for Checkout events and keep customer.subscription.* cases routed to subscription logic. Critically: idempotency dedup on event.id runs before any case, because Stripe webhooks are at-least-once delivery [4].

The handler that ships with SecureStartKit already routes both event families. The migration-window pattern adds an outer dedup table and a discriminator on session.mode:

// app/api/webhooks/stripe/route.ts (dual-mode, migration-window)
import { headers } from 'next/headers'
import { NextResponse } from 'next/server'
import { getStripe } from '@/lib/stripe/client'
import { createAdminClient } from '@/lib/supabase/server'
import type Stripe from 'stripe'

const relevantEvents = new Set([
  // One-time path
  'checkout.session.completed',
  // Legacy subscription path (still live during migration window)
  'customer.subscription.created',
  'customer.subscription.updated',
  'customer.subscription.deleted',
  'invoice.payment_failed',
])

export async function POST(request: Request) {
  const body = await request.text()
  const sig = (await headers()).get('stripe-signature')
  if (!sig) return NextResponse.json({ error: 'No signature' }, { status: 400 })

  let event: Stripe.Event
  try {
    event = getStripe().webhooks.constructEvent(
      body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET!,
    )
  } catch {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 })
  }

  if (!relevantEvents.has(event.type)) {
    return NextResponse.json({ received: true })
  }

  const admin = createAdminClient()

  // Idempotency dedup: Stripe webhooks are at-least-once
  const { error: dedupError } = await admin
    .from('processed_events')
    .insert({ id: event.id, type: event.type })
  if (dedupError?.code === '23505') {
    return NextResponse.json({ received: true, deduped: true })
  }

  try {
    switch (event.type) {
      case 'checkout.session.completed': {
        const session = event.data.object as Stripe.Checkout.Session
        // Mode discriminator: only handle one-time here
        if (session.mode === 'payment') {
          await handleOneTimePurchase(admin, session)
        }
        // Subscription mode sessions are now closed to NEW signups during migration
        break
      }

      case 'customer.subscription.updated': {
        const sub = event.data.object as Stripe.Subscription
        await handleScheduledCancellation(admin, sub)
        break
      }

      case 'customer.subscription.deleted': {
        const sub = event.data.object as Stripe.Subscription
        await handleSubscriptionEnded(admin, sub)
        break
      }

      case 'invoice.payment_failed': {
        // Legacy dunning still runs for unmigrated cohorts
        break
      }
    }
    return NextResponse.json({ received: true })
  } catch (err) {
    console.error('Webhook handler error:', err)
    return NextResponse.json({ error: 'Handler failed' }, { status: 500 })
  }
}

The signature verification mechanics (stripe-signature header, constructEvent, the 300-second default tolerance, raw-body requirement in App Router) are unchanged for either mode. The deep dive on what makes that step go wrong lives in Stripe webhook signature verification in Next.js. The one place migration adds risk is when a developer adds the new checkout.session.completed handler without verifying the same raw-body pattern is in place for the subscription cases that were working before; mismatched parsing breaks one mode while the other looks fine. Test both paths with the Stripe webhook verifier tool before deploying the migration.

One subtle case: checkout.session.completed also fires for subscription Checkout sessions, with session.mode === 'subscription'. During a migration where you have closed new subscription signups, you should not be creating subscription Checkout sessions at all, so this case becomes a noop. Keeping the explicit session.mode === 'payment' check protects against the case where stale frontend code on a customer's machine creates a subscription session by accident.

How do you prevent the access-revocation race condition?

The race condition is this: a customer hits "cancel my subscription" on day 14 of a 30-day billing cycle. The Server Action sets cancel_at_period_end: true. The webhook handler receives customer.subscription.updated with cancel_at_period_end: true AND status: 'active'. The customer should keep access for 16 more days, then lose it. The naive handler treats "cancel_at_period_end is now true" as "revoke access now" and locks the customer out two minutes after they confirmed the cancellation they thought was for the future.

The fix is to read the subscription's status, not the cancel_at_period_end flag, when deciding whether to grant access. The flag is bookkeeping for the future; the status is the source of truth for now. Update your access-gating code:

// Wrong: revokes immediately on the flag flip
const isActive = (sub: Subscription) =>
  sub.status === 'active' && !sub.cancel_at_period_end

// Right: status is the source of truth for current access
const isActive = (sub: Subscription) =>
  sub.status === 'active' || sub.status === 'trialing'

The handler updates persist BOTH fields so the rest of the app can read them independently:

async function handleScheduledCancellation(admin, sub: Stripe.Subscription) {
  await admin.from('subscriptions').upsert({
    id: sub.id,
    status: sub.status, // still 'active' until period end
    cancel_at_period_end: sub.cancel_at_period_end, // true now, signals UI
    current_period_end: new Date(sub.current_period_end * 1000).toISOString(),
    updated_at: new Date().toISOString(),
  })
  // Comms: send the cancellation-scheduled email, NOT the access-revoked email
  await sendCancellationScheduledEmail(sub.customer as string, sub.current_period_end)
}

async function handleSubscriptionEnded(admin, sub: Stripe.Subscription) {
  await admin
    .from('subscriptions')
    .update({
      status: 'canceled', // NOW access is gone
      ended_at: new Date().toISOString(),
    })
    .eq('id', sub.id)
  // Comms: send the access-revoked email
  await sendAccessRevokedEmail(sub.customer as string)
}

The second piece of the race is the migration-window double-purchase. A customer is mid-cancellation (subscription is status: 'active', cancel_at_period_end: true) and also goes through the new one-time Checkout for the migrated product. They now have BOTH an active subscription AND a completed one-time purchase. The handler for checkout.session.completed cannot just grant access because the subscription handler is also granting access for the remaining 16 days. Without coordination, the customer's "do I have access" check reads true from two independent records, and when the subscription ends in 16 days, one of them flips to false while the other stays true. The customer keeps access. Fine, intentional in this case. But the application has to be ready for the "user has both" intermediate state, not surprised by it.

The cleanest pattern is a unified entitlement view that takes the disjunction:

create or replace view public.user_entitlements as
select
  u.id as user_id,
  (
    exists (
      select 1 from subscriptions s
      where s.user_id = u.id and s.status in ('active', 'trialing')
    )
    or
    exists (
      select 1 from purchases p
      where p.user_id = u.id and p.status = 'completed'
    )
  ) as has_access
from auth.users u;

Now access checks read one boolean from one source. During the migration window the boolean is true via both paths for some users; after migration it is true via the purchases path only. The transition is invisible to the application layer, which is the point.

For the broader architectural posture on routing every read and write through Server Actions instead of trusting client-side state, see backend-only data access. The entitlement view above is the canonical example of a backend-only access primitive: client code never reads subscriptions or purchases directly, only the view.

What should your customer-comms templates say at each Stripe state transition?

One email template per webhook trigger. The mapping is explicit, no inference from application state.

Stripe event	Email template	When to send	Subject line
customer.subscription.updated with cancel_at_period_end: true	Cancellation scheduled	At the moment the flag is flipped	"Your subscription is scheduled to end on "
customer.subscription.deleted (Mode A)	Access revoked, transition CTA	When the period actually ends	"Your subscription has ended. Here is how to switch to one-time billing."
customer.subscription.deleted (Mode B)	Refund issued, access revoked	At immediate cancel	"Your subscription has been canceled and a refund of has been issued."
checkout.session.completed with mode: 'payment'	One-time purchase confirmation	At new purchase completion	"Welcome to . Here is your access."
invoice.payment_failed (legacy dunning, last cycle)	Dunning notice	On any failed renewal during the migration window	"We could not charge . Here is what to do."

The cancellation-scheduled email is the most error-prone in practice. It needs to communicate three things: the cancellation will take effect on a specific date (not today), the customer keeps access until then, and there is a one-click path to the new one-time product if they want to transition early. The body language matters because customers reading "your subscription is canceled" expect immediate effect; "your subscription is scheduled to end" preempts the support ticket.

A working template body for Mode A cancellations:

Hi {customer_name},

Your subscription to {product_name} is scheduled to end on {period_end_date}.
Until that date, you have full access. We won't charge you again.

If you'd like to keep using {product_name} after {period_end_date}, you can
switch to one-time billing here: {one_time_checkout_url}

If this was a mistake, you can cancel the cancellation by logging into your
billing portal and clicking "Resume Subscription".

Thanks for being a customer.

The "cancel the cancellation" mechanic works only for Mode A before the period ends. Stripe explicitly supports it: "You can reactivate subscriptions scheduled for cancellation by updating cancel_at_period_end to false." [3] Once customer.subscription.deleted fires, reactivation is no longer possible and a new subscription (or one-time purchase) is the only path.

Wire the email-send calls inside the handler, not in the application's Server Actions. The handler is the one place that knows for certain which Stripe state transition happened, and it runs idempotently because of the dedup on event.id. A Server Action that initiates a cancel and then tries to send the confirmation email has two race conditions: the webhook might fire first (double email) or Stripe might fail the cancellation after the email sent (false email). The webhook is the source of truth; the email is a side effect of the webhook.

What are the 5 failure modes that ambush founders mid-migration?

The five symptoms below cover roughly 90% of mid-migration support tickets. Each has a distinct signature and a one-pass fix.

Failure 1: Customers locked out immediately when they scheduled a future cancellation

Signature: Customer cancels via the billing portal. Within minutes, their access is gone. They were expecting to keep access until renewal.

Root cause: Access-gating logic reads cancel_at_period_end as the cancellation signal. When the flag flips to true, the app treats the subscription as canceled. But cancel_at_period_end: true is a future-tense signal; status: 'active' is the present-tense reality.

Fix: Switch the access-gating predicate from !cancel_at_period_end to status === 'active' || status === 'trialing'. The flag is bookkeeping for the UI ("show the 'subscription ending' banner") and for analytics, not for access. Re-test by setting cancel_at_period_end: true on a test subscription and confirming access continues until the simulated period end.

Failure 2: Access revocation weeks late because handler ignored cancel_at_period_end entirely

Signature: A subscription canceled mid-period continues to work. The customer's access only disappears at the period end, weeks later, with no email or transition path.

Root cause: The webhook handler only processes customer.subscription.deleted and ignores customer.subscription.updated. The handler is technically correct (access should not be revoked until .deleted fires), but the customer received no communication when they actually clicked cancel, so the experience is silent and confusing.

Fix: Add the customer.subscription.updated case to the handler. On cancel_at_period_end: true, do not change the access state, but DO send the cancellation-scheduled email and update a UI flag in the application database. The customer gets the cancellation confirmation they expect; the access continues through the paid period as Stripe intends.

Failure 3: Double-billed during migration because dual-mode handler routes wrong

Signature: A customer's card gets charged twice in the same period: once for the subscription renewal that fires before they migrate, once for the one-time purchase. Refund tickets pile up.

Root cause: The dual-mode handler does not check session.mode on checkout.session.completed. A subscription Checkout that completes during the migration window fires the same event as a one-time Checkout. Without the discriminator, both flow through the one-time grant path, which double-grants entitlement. Worse, the subscription's recurring charges still fire on their schedule because the subscription itself was never canceled.

Fix: Two changes. First, close new subscription Checkout creation entirely at the moment migration begins (the price IDs for the subscription products should not be reachable from the application). Second, always check session.mode === 'payment' in the checkout.session.completed handler, so a subscription Checkout that somehow gets through (legacy code, stale tab) becomes a noop instead of a double-grant.

Failure 4: Webhook signature failures spike during migration because handler is changed mid-deploy

Signature: Stripe webhook deliveries start failing with 400 status codes. The dashboard shows "Invalid signature" on a high percentage of events. Some events get retried for three days [4] and clog the queue.

Root cause: The handler was modified to add new cases but the raw-body parsing got changed at the same time (someone moved to request.json() because the new cases looked cleaner without request.text()). The byte representation differs, the HMAC signature fails to verify, every event 400s.

Fix: Keep await request.text() as the body retrieval call regardless of how many cases the switch statement grows. The signature verification is byte-exact; any reformatting breaks it. The full walkthrough on the 5 webhook signature failure modes that intersect with this one is in Stripe webhook signature verification in Next.js. Stripe's default tolerance is 5 minutes (300s) between the signed timestamp and your server's clock [4], so a clock drift during the migration deploy can also masquerade as a signature failure.

Failure 5: Customers email asking why they were not refunded after canceling

Signature: Customers expected a refund when they canceled. They got no refund. Inbox fills with confused emails.

Root cause: The cancellation flow used Mode A (cancel_at_period_end: true) when the business intent was Mode B (immediate cancel with proration). Customers reading "subscription canceled" assume their money for the unused period is coming back. Without prorate: true and invoice_now: true, Stripe issues no proration credit; the subscription quietly runs out at period end with no refund.

Fix: Decide the policy per cohort before the migration starts. If the policy is no-refund (most common for SaaS), Mode A is correct AND the cancellation email must explicitly say "your card will not be charged again; you keep access until ; no refund will be issued for the current period." If the policy is refund-on-exit, use Mode B with both flags, and the email confirms "a refund of has been issued for the unused portion of your subscription." The wording is non-negotiable; ambiguity here is what fills the support queue.

When does a Stripe migration mean you should rethink the architecture?

A subscription-to-one-time migration is often a healthier choice than the implicit alternative, which is "keep limping subscription mode along while half the team wants to switch." The four steps and five failure modes above are tractable. But the migration is also a forcing function for the architectural question one layer deeper: should the application's billing surface be coupled to Stripe's data model at all?

The pattern most indie SaaS apps end up with is direct reads from subscriptions.status scattered across the codebase, every access check tightly bound to whatever Stripe is currently saying. That works until a migration like this one, when every direct read is a place that has to be updated for the new model. The cleaner pattern is to route every billing read through a single backend-only entitlement primitive (the unified view from earlier in this post is the simplest version) and let Stripe-shaped data live in the webhook handler and a few thin adapters.

SecureStartKit ships with mode: 'payment' as the default precisely because that decision is reversible and one-time billing has the smaller blast radius if you decide to add subscription later. The architectural cost was already paid in the dual-mode handler; the billing architecture pillar walks the full trade-off across the 6 mechanical differences. For the broader Server Actions pattern that makes this kind of migration safe to run on live traffic (validate then authorize then query, idempotency at the data layer, signed webhooks with replay protection), see how to add Stripe payments to Next.js using Server Actions.

The migration itself is a four-step procedure: pick the cancellation mode per cohort, route the webhook handler dual-mode, gate access on status rather than the flag, and send comms anchored 1:1 to the webhook events. The five failure modes name the specific places that procedure breaks under production traffic. If you are starting fresh today, the comparison page is the decision tool, and choosing one-time from day one skips this migration entirely. If you are already on subscription and the value-delivery shape no longer fits, this is the path.