Mastering Subscription Prorations: Handling Complex Billing Changes in Production

// app/api/stripe-webhooks/route.ts (Next.js App Router)

import Stripe from 'stripe';
import { headers } from 'next/headers';
import { buffer } from 'micro'; // Or your preferred body parser
import { createClient } from '@supabase/supabase-js';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2023-10-16',
});

// Initialize Supabase client
const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

export async function POST(req: Request) {
  const rawBody = await buffer(req); // Read raw body for Stripe signature verification
  const signature = headers().get('stripe-signature');

  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(
      rawBody,
      signature!,
      process.env.STRIPE_WEBHOOK_SECRET! // Your webhook secret
    );
  } catch (err: any) {
    console.error(`Webhook signature verification failed: ${err.message}`);
    return new Response(`Webhook Error: ${err.message}`, { status: 400 });
  }

  // Check if the event has already been processed using a unique event ID
  const { data: existingEvent, error: fetchError } = await supabase
    .from('processed_stripe_events')
    .select('id')
    .eq('event_id', event.id)
    .single();

  if (fetchError && fetchError.code !== 'PGRST116') { // PGRST116 means no rows found
    console.error('Database error checking event:', fetchError);
    return new Response('Internal Server Error', { status: 500 });
  }

  if (existingEvent) {
    console.log(`Skipping duplicate event: ${event.id}`);
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // Store the event ID before processing to prevent race conditions on subsequent retries
  const { error: insertError } = await supabase
    .from('processed_stripe_events')
    .insert({ event_id: event.id, created_at: new Date().toISOString() });

  if (insertError) {
    // This might happen if two webhook deliveries arrive almost simultaneously
    // and both try to insert. The unique constraint on event_id will prevent true duplicates.
    // We can safely assume if insert fails due to unique constraint, another process is handling it.
    if (insertError.code === '23505') { // Unique violation error code
      console.warn(`Race condition detected for event ${event.id}, another process is likely handling it.`);
      return new Response(JSON.stringify({ received: true }), { status: 200 });
    } else {
      console.error('Error inserting event ID:', insertError);
      return new Response('Internal Server Error', { status: 500 });
    }
  }

  switch (event.type) {
    case 'customer.subscription.updated':
      const subscription = event.data.object as Stripe.Subscription;
      // Implement your logic to update the user's subscription in your database
      // Ensure this logic is also idempotent. For example, only update if
      // the received subscription's `updated` timestamp is newer than your stored one.
      console.log(`Subscription ${subscription.id} updated. Status: ${subscription.status}`);
      // Example: update user's plan in Supabase
      const { error: updateError } = await supabase
        .from('user_subscriptions')
        .upsert(
          { 
            stripe_subscription_id: subscription.id, 
            user_id: subscription.metadata.user_id, // Assuming you store user_id in metadata
            status: subscription.status,
            current_plan_id: subscription.items.data[0]?.price?.id, // Get current price ID
            // ... other relevant fields like 'current_period_end'
          },
          { onConflict: 'stripe_subscription_id' }
        );
      
      if (updateError) {
        console.error('Error updating user subscription:', updateError);
        // Consider retrying or alerting here
      }
      break;
    // Handle other relevant events like 'invoice.payment_succeeded', 'invoice.payment_failed'
    default:
      console.log(`Unhandled event type ${event.type}`);
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}

// Note: You'll need a 'processed_stripe_events' table in Supabase
// CREATE TABLE processed_stripe_events (
//   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
//   event_id TEXT UNIQUE NOT NULL,
//   created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
// );

// Example: Previewing a subscription update
async function previewSubscriptionUpdate(subscriptionId: string, newPriceId: string) {
  try {
    const subscription = await stripe.subscriptions.retrieve(subscriptionId);
    const currentPriceId = subscription.items.data[0].price?.id;

    if (!currentPriceId) {
      throw new Error('Could not determine current subscription price.');
    }

    // Simulate the update to get proration details
    const upcomingInvoice = await stripe.invoices.retrieveUpcoming({
      customer: subscription.customer as string,
      subscription: subscriptionId,
      subscription_items: [
        {
          id: subscription.items.data[0].id,
          price: newPriceId,
        },
      ],
      subscription_proration_behavior: 'always_invoice',
    });

    // Extract relevant proration details for display
    const totalDue = upcomingInvoice.total;
    const creditApplied = upcomingInvoice.credit_balance; // or other relevant fields
    const lines = upcomingInvoice.lines.data;

    console.log(`Preview: Total due for next invoice: ${totalDue}`);
    console.log(`Preview: Credits applied: ${creditApplied}`);
    // Parse 'lines' to show specific prorated charges/credits

    return { totalDue, creditApplied, lines };

  } catch (error) {
    console.error('Error previewing subscription update:', error);
    throw error;
  }
}