// Creating a product and price via Stripe API (can also be done in dashboard)
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

const product = await stripe.products.create({
  name: 'Pro Plan',
  description: 'Full access to all features'
});

const price = await stripe.prices.create({
  unit_amount: 4900,         // $49.00 in cents
  currency: 'usd',
  recurring: { interval: 'month' },
  product: product.id
});

console.log('Price ID:', price.id);
// Store this Price ID — you will reference it in checkout sessions

# .env
STRIPE_SECRET_KEY=sk_live_xxxxxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxx
STRIPE_PRO_MONTHLY_PRICE_ID=price_xxxxxxxx
STRIPE_PRO_ANNUAL_PRICE_ID=price_xxxxxxxx

// POST /api/billing/create-checkout-session
app.post('/api/billing/create-checkout-session', requireAuth, async (req, res) => {
  const { priceId } = req.body;
  const user = req.user;

  try {
    // Retrieve or create a Stripe customer for this user
    let customerId = user.stripeCustomerId;

    if (!customerId) {
      const customer = await stripe.customers.create({
        email: user.email,
        metadata: { userId: user.id }   // Critical: links Stripe customer to your DB user
      });
      customerId = customer.id;

      // Persist the customer ID immediately
      await db.users.update({ stripeCustomerId: customerId }, { where: { id: user.id } });
    }

    const session = await stripe.checkout.sessions.create({
      customer: customerId,
      payment_method_types: ['card'],
      line_items: [{ price: priceId, quantity: 1 }],
      mode: 'subscription',
      success_url: `${process.env.APP_URL}/dashboard?billing=success`,
      cancel_url: `${process.env.APP_URL}/pricing`,
      subscription_data: {
        metadata: { userId: user.id }   // Attach user ID to the subscription too
      }
    });

    res.json({ url: session.url });
  } catch (err) {
    console.error('Checkout session error:', err);
    res.status(500).json({ error: 'Failed to create checkout session' });
  }
});

// POST /api/billing/webhook
// IMPORTANT: This route must use raw body parsing, not JSON parsing
app.post('/api/billing/webhook',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const sig = req.headers['stripe-signature'];
    let event;

    try {
      event = stripe.webhooks.constructEvent(
        req.body,
        sig,
        process.env.STRIPE_WEBHOOK_SECRET
      );
    } catch (err) {
      console.error('Webhook signature verification failed:', err.message);
      return res.status(400).send(`Webhook Error: ${err.message}`);
    }

    // Process the event
    await handleStripeEvent(event);
    res.json({ received: true });
  }
);

async function handleStripeEvent(event) {
  const { type, data } = event;
  const object = data.object;

  switch (type) {

    // Subscription created (after successful first payment)
    case 'customer.subscription.created':
      await db.subscriptions.upsert({
        userId: object.metadata.userId,
        stripeSubscriptionId: object.id,
        stripePriceId: object.items.data[0].price.id,
        status: object.status,
        currentPeriodEnd: new Date(object.current_period_end * 1000),
        cancelAtPeriodEnd: object.cancel_at_period_end
      });
      break;

    // Subscription updated (plan change, renewal, etc.)
    case 'customer.subscription.updated':
      await db.subscriptions.update({
        stripePriceId: object.items.data[0].price.id,
        status: object.status,
        currentPeriodEnd: new Date(object.current_period_end * 1000),
        cancelAtPeriodEnd: object.cancel_at_period_end
      }, { where: { stripeSubscriptionId: object.id } });
      break;

    // Subscription cancelled or payment permanently failed
    case 'customer.subscription.deleted':
      await db.subscriptions.update({
        status: 'canceled'
      }, { where: { stripeSubscriptionId: object.id } });
      break;

    // THIS IS THE EVENT MOST TUTORIALS MISS #1
    // Triggered on each successful renewal payment
    case 'invoice.payment_succeeded':
      if (object.billing_reason === 'subscription_cycle') {
        await db.subscriptions.update({
          status: 'active',
          currentPeriodEnd: new Date(object.lines.data[0].period.end * 1000)
        }, { where: { stripeSubscriptionId: object.subscription } });
      }
      break;

    // THIS IS THE EVENT MOST TUTORIALS MISS #2
    // Triggered when a renewal payment fails
    case 'invoice.payment_failed':
      await db.subscriptions.update({
        status: 'past_due'
      }, { where: { stripeSubscriptionId: object.subscription } });
      // Optionally: trigger an email notification to the user
      await sendPaymentFailedEmail(object.customer_email);
      break;

    default:
      // Unhandled event type — log and continue
      console.log(`Unhandled Stripe event: ${type}`);
  }
}

CREATE TABLE subscriptions (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id         UUID NOT NULL REFERENCES users(id),
  stripe_subscription_id VARCHAR(255) UNIQUE NOT NULL,
  stripe_price_id        VARCHAR(255) NOT NULL,
  status                 VARCHAR(50) NOT NULL,  -- active, past_due, canceled, trialing
  current_period_end     TIMESTAMP NOT NULL,
  cancel_at_period_end   BOOLEAN DEFAULT FALSE,
  created_at             TIMESTAMP DEFAULT NOW(),
  updated_at             TIMESTAMP DEFAULT NOW()
);

// Middleware to check subscription access
async function requireActiveSubscription(req, res, next) {
  const subscription = await db.subscriptions.findOne({
    where: { userId: req.user.id }
  });

  const isActive = subscription &&
    ['active', 'trialing'].includes(subscription.status) &&
    new Date(subscription.currentPeriodEnd) > new Date();

  if (!isActive) {
    return res.status(403).json({ error: 'Active subscription required' });
  }

  next();
}

// POST /api/billing/portal
app.post('/api/billing/portal', requireAuth, async (req, res) => {
  try {
    const session = await stripe.billingPortal.sessions.create({
      customer: req.user.stripeCustomerId,
      return_url: `${process.env.APP_URL}/dashboard`
    });

    res.json({ url: session.url });
  } catch (err) {
    res.status(500).json({ error: 'Failed to open billing portal' });
  }
});

# Install Stripe CLI and listen for local webhooks
stripe listen --forward-to localhost:3000/api/billing/webhook

# Simulate specific events
stripe trigger customer.subscription.created
stripe trigger invoice.payment_failed
stripe trigger customer.subscription.deleted

Why does my webhook keep returning 400 errors?

The most common cause is JSON body parsing running before the raw body parser on the webhook route. Ensure express.raw() is applied specifically to /api/billing/webhook and that express.json() is not globally applied before it.

Should I use Stripe Checkout or a custom payment form?

Stripe Checkout handles 3D Secure, card validation, tax calculation, and localization automatically. Custom payment forms require explicit handling of all of these. For SaaS subscriptions, Checkout is the correct starting point for the large majority of use cases.

How do I handle the period between a failed payment and subscription cancellation?

Stripe's dunning configuration (in dashboard settings) determines how many retry attempts are made and over what period. During this window, the subscription status is past_due. Surfacing an in-app banner to users in past_due status — directing them to the billing portal to update their payment method — reduces involuntary churn significantly.

Can I let users switch between monthly and annual plans?

Yes, via the Stripe Customer Portal or by using stripe.subscriptions.update() with a new price ID and proration_behavior: 'create_prorations'. The billing portal handles this with no code required if configured correctly.