Handle subscription scheduled webhook events

Author: jahooma

packages/billing/src/subscription-webhooks.ts

@@ -220,6 +220,12 @@ export async function handleSubscriptionInvoicePaymentFailed(params: {
 
 /**
  * Syncs plan details and cancellation intent from Stripe.
+ *
+ * Note: Downgrade scheduling is handled by subscription_schedule webhooks.
+ * When a user downgrades via Customer Portal with "Wait until end of billing
+ * period", Stripe creates a subscription schedule rather than immediately
+ * changing the subscription price. The handleSubscriptionScheduleCreatedOrUpdated
+ * handler sets scheduled_tier based on the schedule's phases.
  */
 export async function handleSubscriptionUpdated(params: {
   stripeSubscription: Stripe.Subscription
@@ -259,22 +265,20 @@ export async function handleSubscriptionUpdated(params: {
 
   const status = mapStripeStatus(stripeSubscription.status)
 
-  // Check existing tier to detect downgrades. During a downgrade the old
-  // higher tier is kept in `scheduled_tier` so limits remain until renewal.
+  // Check existing tier to detect upgrades for block grant expiration.
   const existingSub = await db
     .select({
       tier: schema.subscription.tier,
-      scheduled_tier: schema.subscription.scheduled_tier,
     })
     .from(schema.subscription)
     .where(eq(schema.subscription.stripe_subscription_id, subscriptionId))
     .limit(1)
 
   const existingTier = existingSub[0]?.tier
-  const isDowngrade = existingTier != null && existingTier > tier
 
   // Upsert — webhook ordering is not guaranteed by Stripe, so this event
   // may arrive before invoice.paid creates the row.
+  // Note: We don't modify scheduled_tier here; that's managed by schedule webhooks.
   await db
     .insert(schema.subscription)
     .values({
@@ -296,11 +300,8 @@ export async function handleSubscriptionUpdated(params: {
       target: schema.subscription.stripe_subscription_id,
       set: {
         user_id: userId,
-        // Downgrade: preserve current tier & stripe_price_id, schedule the
-        // new tier for the next billing period.
-        ...(isDowngrade
-          ? { scheduled_tier: tier }
-          : { tier, stripe_price_id: priceId, scheduled_tier: null }),
+        tier,
+        stripe_price_id: priceId,
         status,
         cancel_at_period_end: stripeSubscription.cancel_at_period_end,
         billing_period_start: new Date(
@@ -325,12 +326,9 @@ export async function handleSubscriptionUpdated(params: {
     {
       subscriptionId,
       cancelAtPeriodEnd: stripeSubscription.cancel_at_period_end,
-      isDowngrade,
       isUpgrade,
     },
-    isDowngrade
-      ? 'Processed subscription update — downgrade scheduled for next billing period'
-      : 'Processed subscription update',
+    'Processed subscription update',
   )
 }
 
@@ -375,3 +373,173 @@ export async function handleSubscriptionDeleted(params: {
 
   logger.info({ subscriptionId }, 'Subscription canceled')
 }
+
+// ---------------------------------------------------------------------------
+// subscription_schedule.created / subscription_schedule.updated
+// ---------------------------------------------------------------------------
+
+/**
+ * Handles subscription schedule creation or updates.
+ *
+ * When a user schedules a downgrade via Stripe Customer Portal (with "Wait
+ * until end of billing period"), Stripe creates a subscription schedule with
+ * multiple phases. Phase 0 is the current state, phase 1+ contains the
+ * scheduled changes.
+ *
+ * This handler extracts the scheduled tier from the next phase and stores it
+ * in our database so we can show the pending change to the user and apply
+ * appropriate limits at renewal.
+ */
+export async function handleSubscriptionScheduleCreatedOrUpdated(params: {
+  schedule: Stripe.SubscriptionSchedule
+  logger: Logger
+}): Promise<void> {
+  const { schedule, logger } = params
+
+  // Only process active schedules
+  if (schedule.status !== 'active') {
+    logger.debug(
+      { scheduleId: schedule.id, status: schedule.status },
+      'Ignoring non-active subscription schedule',
+    )
+    return
+  }
+
+  // Get the linked subscription ID
+  const subscriptionId = schedule.subscription
+    ? getStripeId(schedule.subscription)
+    : null
+
+  if (!subscriptionId) {
+    logger.warn(
+      { scheduleId: schedule.id },
+      'Subscription schedule has no linked subscription — skipping',
+    )
+    return
+  }
+
+  // Need at least 2 phases to have a scheduled change (current + future)
+  if (!schedule.phases || schedule.phases.length < 2) {
+    logger.debug(
+      { scheduleId: schedule.id, subscriptionId, phases: schedule.phases?.length },
+      'Subscription schedule has fewer than 2 phases — no scheduled change',
+    )
+    return
+  }
+
+  // Extract the scheduled tier from the next phase (phase 1)
+  const nextPhase = schedule.phases[1]
+  const scheduledPriceId = nextPhase?.items?.[0]?.price
+  const priceId = typeof scheduledPriceId === 'string'
+    ? scheduledPriceId
+    : scheduledPriceId?.toString()
+
+  if (!priceId) {
+    logger.warn(
+      { scheduleId: schedule.id, subscriptionId },
+      'Subscription schedule next phase has no price — skipping',
+    )
+    return
+  }
+
+  const scheduledTier = getTierFromPriceId(priceId)
+  if (!scheduledTier) {
+    logger.debug(
+      { scheduleId: schedule.id, subscriptionId, priceId },
+      'Scheduled price ID does not match a Strong tier — skipping',
+    )
+    return
+  }
+
+  // Update the subscription with the scheduled tier
+  const result = await db
+    .update(schema.subscription)
+    .set({
+      scheduled_tier: scheduledTier,
+      updated_at: new Date(),
+    })
+    .where(eq(schema.subscription.stripe_subscription_id, subscriptionId))
+    .returning({ tier: schema.subscription.tier })
+
+  if (result.length === 0) {
+    logger.warn(
+      { scheduleId: schedule.id, subscriptionId, scheduledTier },
+      'No subscription found to update with scheduled tier — may arrive before subscription created',
+    )
+    return
+  }
+
+  const currentTier = result[0]?.tier
+
+  logger.info(
+    {
+      scheduleId: schedule.id,
+      subscriptionId,
+      currentTier,
+      scheduledTier,
+      scheduledStartDate: nextPhase.start_date
+        ? new Date(nextPhase.start_date * 1000).toISOString()
+        : null,
+    },
+    'Set scheduled tier from subscription schedule',
+  )
+}
+
+// ---------------------------------------------------------------------------
+// subscription_schedule.released / subscription_schedule.canceled
+// ---------------------------------------------------------------------------
+
+/**
+ * Handles subscription schedule release or cancellation.
+ *
+ * When a schedule is released (completes and detaches from the subscription)
+ * or canceled (user cancels the pending change), we clear the scheduled_tier.
+ *
+ * Note: When a schedule "releases" after applying its final phase, the
+ * subscription itself gets updated, which triggers invoice.paid at renewal.
+ * That handler already clears scheduled_tier, but this provides a safety net.
+ */
+export async function handleSubscriptionScheduleReleasedOrCanceled(params: {
+  schedule: Stripe.SubscriptionSchedule
+  logger: Logger
+}): Promise<void> {
+  const { schedule, logger } = params
+
+  const subscriptionId = schedule.subscription
+    ? getStripeId(schedule.subscription)
+    : null
+
+  if (!subscriptionId) {
+    logger.debug(
+      { scheduleId: schedule.id },
+      'Released/canceled schedule has no subscription — skipping',
+    )
+    return
+  }
+
+  const result = await db
+    .update(schema.subscription)
+    .set({
+      scheduled_tier: null,
+      updated_at: new Date(),
+    })
+    .where(eq(schema.subscription.stripe_subscription_id, subscriptionId))
+    .returning({ tier: schema.subscription.tier })
+
+  if (result.length === 0) {
+    logger.debug(
+      { scheduleId: schedule.id, subscriptionId },
+      'No subscription found when clearing scheduled tier — may already be deleted',
+    )
+    return
+  }
+
+  logger.info(
+    {
+      scheduleId: schedule.id,
+      subscriptionId,
+      status: schedule.status,
+    },
+    'Cleared scheduled tier after subscription schedule released/canceled',
+  )
+}

web/src/app/api/stripe/webhook/route.ts

@@ -6,6 +6,8 @@ import {
   handleSubscriptionInvoicePaymentFailed,
   handleSubscriptionUpdated,
   handleSubscriptionDeleted,
+  handleSubscriptionScheduleCreatedOrUpdated,
+  handleSubscriptionScheduleReleasedOrCanceled,
 } from '@codebuff/billing'
 import db from '@codebuff/internal/db'
 import * as schema from '@codebuff/internal/db/schema'
@@ -390,6 +392,25 @@ const webhookHandler = async (req: NextRequest): Promise<NextResponse> => {
         }
         break
       }
+      case 'subscription_schedule.created':
+      case 'subscription_schedule.updated': {
+        const schedule = event.data.object as Stripe.SubscriptionSchedule
+        // Skip organization schedules (if they have org metadata)
+        if (!schedule.metadata?.organization_id) {
+          await handleSubscriptionScheduleCreatedOrUpdated({ schedule, logger })
+        }
+        break
+      }
+      case 'subscription_schedule.completed':
+      case 'subscription_schedule.released':
+      case 'subscription_schedule.canceled': {
+        const schedule = event.data.object as Stripe.SubscriptionSchedule
+        // Skip organization schedules (if they have org metadata)
+        if (!schedule.metadata?.organization_id) {
+          await handleSubscriptionScheduleReleasedOrCanceled({ schedule, logger })
+        }
+        break
+      }
       case 'charge.dispute.created': {
         const dispute = event.data.object as Stripe.Dispute