DEV Community

Cover image for How to Add Stripe Subscriptions to an AI-Generated App (Step by Step)
Aadesh Kumar
Aadesh Kumar

Posted on

How to Add Stripe Subscriptions to an AI-Generated App (Step by Step)

#webdev #saas #stripe #nocode

Most Stripe tutorials stop at the payment form. This one covers what comes after.

What you will learn in this guide:

  • How to configure Stripe Billing products and price objects correctly from the start
  • How to build the checkout session flow for subscription plans
  • How to handle Stripe webhooks reliably — including the two events most tutorials omit
  • How to manage subscription state in your database across plan changes, upgrades, and cancellations
  • How to surface a working billing portal without building one from scratch

Why Stripe Subscriptions Are Harder Than They Look

Stripe's documentation is thorough. It is also large enough that developers routinely wire up payment forms, test a successful charge, and ship — without realizing that the critical parts of a subscription integration happen after the initial payment.

Subscription management means handling renewals, failed payments, plan upgrades, downgrades, and cancellations — all asynchronously, via webhooks, with state that has to be reflected accurately in your own database.

AI-generated apps frequently scaffold the checkout flow correctly but leave the post-payment state management incomplete. This guide fills that gap.

The code examples use Node.js with Express, but the architectural patterns apply to any backend stack.

Step 1: Set Up Your Stripe Products and Prices

Before writing any code, the Stripe dashboard configuration determines how flexible and maintainable your billing logic will be.

Create a Product in the Stripe dashboard for each tier of your SaaS (e.g., Starter, Pro, Enterprise). Products are the high-level concept; Prices are the billing intervals and amounts attached to them.

// 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
Enter fullscreen mode Exit fullscreen mode

Key principle: Store your Price IDs in environment variables, not hardcoded in your application. When you add annual billing or change a plan's price, you update a variable rather than hunting through code.

# .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
Enter fullscreen mode Exit fullscreen mode

Step 2: Build the Checkout Session

Stripe Checkout handles the payment form, card validation, and 3D Secure authentication. The correct approach is to create a server-side Checkout Session and redirect the user — never build a custom payment form for subscriptions unless you have a specific regulatory requirement.

// 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' });
  }
});
Enter fullscreen mode Exit fullscreen mode

The metadata: { userId: user.id } on both the customer and the subscription is the most commonly missed step in AI-generated integrations. Without it, webhook handlers cannot reliably map Stripe events back to users in your database.

Step 3: Handle Webhooks — The Part Most Tutorials Skip

Webhook handling is where subscription integrations succeed or fail. Stripe sends events for every billing lifecycle change. Your application needs to listen for and process these events to keep your database in sync.

First, set up webhook signature verification. This confirms the event came from Stripe and not a malicious request.

// 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 });
  }
);
Enter fullscreen mode Exit fullscreen mode

The express.raw() middleware on the webhook route is non-negotiable. Stripe's signature verification requires the raw request body. If express.json() parses it first, verification will fail every time.

Now handle the events that actually matter:

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}`);
  }
}
Enter fullscreen mode Exit fullscreen mode

invoice.payment_succeeded on subscription_cycle is how your database learns that a subscription has renewed for another month. Without this handler, your currentPeriodEnd date will expire and you will incorrectly restrict access to paying customers.

invoice.payment_failed is how you detect and respond to failed renewals before Stripe's dunning process results in cancellation. Applications that handle this event can surface in-app notices to users, trigger email nudges, and prevent unnecessary churn.

Step 4: Model Subscription State in Your Database

The webhook handlers above depend on a subscriptions table that reflects Stripe's state. A minimal schema:

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()
);
Enter fullscreen mode Exit fullscreen mode

Gate feature access using the status and current_period_end columns — not just status alone. A subscription in past_due status may still have access until the period ends, depending on your product's grace period policy.

// 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();
}
Enter fullscreen mode Exit fullscreen mode

🔗 Step 5: Surface the Billing Portal

Stripe's Customer Portal handles plan changes, payment method updates, and cancellations — without you building any of that UI.

// 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' });
  }
});
Enter fullscreen mode Exit fullscreen mode

Enable the portal in the Stripe dashboard under Settings > Billing > Customer Portal before testing. Configure which plans customers can switch between and whether they can cancel immediately or at period end.

Where AI-Generated Apps Fit Into This

Some full-stack AI builders scaffold portions of the Stripe integration as part of their generated output. The scaffold quality varies significantly — checkout session creation is commonly handled, but webhook infrastructure and subscription state management are frequently incomplete.

Platforms like this hybrid builder include Stripe and PayPal scaffolding as part of the generated application, with webhook handlers and subscription state management included by default. For teams evaluating whether to build the billing layer from scratch or use pre-scaffolded output, the practical difference is several days of integration work and debugging — primarily in the webhook handling and state management layers covered in this guide.

Testing Your Integration End-to-End

Use Stripe's test mode and the Stripe CLI to simulate the full billing lifecycle before going live:

# 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
Enter fullscreen mode Exit fullscreen mode

Test cards for specific scenarios:

Scenario Card Number
Successful payment 4242 4242 4242 4242
Payment requires authentication 4000 0025 0000 3155
Payment declined 4000 0000 0000 9995
Insufficient funds 4000 0000 0000 9995

Run through the full cycle: subscribe → renew → fail a payment → recover → cancel. Each transition should produce the correct status update in your database.

Common Questions

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.

Further Reading

Top comments (0)