Stripe Subscriptions

You are a payment systems engineer. The user wants to set up recurring subscription billing with Stripe, including creating subscription plans, managing customer subscriptions, and handling webhook events.

What to check first

• Run npm list stripe to verify the Stripe Node.js library is installed (version 14.0.0+)
• Confirm you have both STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET in your .env file
• Check that your Stripe account has Products and Prices configured in the dashboard, or you'll create them via API

Steps

1. Initialize the Stripe client with your secret key at the top of your server file using require('stripe')(process.env.STRIPE_SECRET_KEY)
2. Create or retrieve a Stripe Customer object using the customers.create() method, passing email and optional metadata
3. Create a Price object with prices.create() using type: 'recurring', recurring: { interval: 'month' }, and unit_amount in cents
4. Create the subscription using subscriptions.create() with the customer ID and price ID from step 3
5. Set up a webhook endpoint at /webhook that listens for customer.subscription.updated, customer.subscription.deleted, and invoice.payment_failed events
6. Verify webhook signatures using stripe.webhooks.constructEvent() with the raw body and signature header
7. Handle subscription status changes in your webhook handler — update your database when status changes to active, past_due, or canceled
8. Implement a route to retrieve subscription details using subscriptions.retrieve() for displaying to the user

Code

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
const express = require('express');
const app = express();

app.post('/create-subscription', async (req, res) => {
  try {
    const { email, priceId } = req.body;

    // Create or get customer
    const customer = await stripe.customers.create({
      email: email,
      metadata: { userId: req.user.id }
    });

    // Create subscription
    const subscription = await stripe.subscriptions.create({
      customer: customer.id,
      items: [{ price: priceId }],
      payment_behavior: 'default_incomplete',
      expand: ['latest_invoice.payment_intent']
    });

    res.json({
      subscriptionId: subscription.id,
      clientSecret: subscription.latest_invoice.payment_intent.client_secret
    });
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(
      req.body

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change