How to upgrade or downgrade a subscription in Stripe

1const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
2
3const subscription = await stripe.subscriptions.retrieve('sub_xxx');
4const currentItem = subscription.items.data[0];
5
6console.log('Item ID:', currentItem.id);           // si_xxx
7console.log('Current Price:', currentItem.price.id); // price_basic
8console.log('Amount:', currentItem.price.unit_amount); // 1000 ($10/mo)

1const preview = await stripe.invoices.retrieveUpcoming({
2  customer: subscription.customer,
3  subscription: subscription.id,
4  subscription_items: [
5    {
6      id: currentItem.id,
7      price: 'price_pro', // New plan Price ID
8    },
9  ],
10});
11
12// Calculate net proration
13const prorationLines = preview.lines.data.filter((line) => line.proration);
14const prorationTotal = prorationLines.reduce((sum, line) => sum + line.amount, 0);
15
16console.log('Proration amount:', prorationTotal); // Positive = charge, Negative = credit
17console.log('Next invoice total:', preview.amount_due);

1const updated = await stripe.subscriptions.update('sub_xxx', {
2  items: [
3    {
4      id: currentItem.id,   // MUST include the item ID to replace
5      price: 'price_pro',    // New plan
6    },
7  ],
8  proration_behavior: 'create_prorations', // Default: add to next invoice
9});
10
11console.log('New plan:', updated.items.data[0].price.id);
12console.log('Status:', updated.status);

1// create_prorations (default): Prorated charges/credits added to next invoice
2await stripe.subscriptions.update('sub_xxx', {
3  items: [{ id: itemId, price: 'price_pro' }],
4  proration_behavior: 'create_prorations',
5});
6
7// always_invoice: Invoice and charge immediately for upgrades
8await stripe.subscriptions.update('sub_xxx', {
9  items: [{ id: itemId, price: 'price_pro' }],
10  proration_behavior: 'always_invoice',
11});
12
13// none: No proration — new price starts at next billing cycle
14await stripe.subscriptions.update('sub_xxx', {
15  items: [{ id: itemId, price: 'price_basic' }],
16  proration_behavior: 'none',
17});

1// 1. Create a subscription on price_basic ($10/mo)
2// 2. After 15 days, upgrade to price_pro ($25/mo)
3// Expected proration:
4//   Credit: $5.00 (15 unused days of $10 plan)
5//   Charge: $12.50 (15 days of $25 plan)
6//   Net charge: $7.50
7
8// Use test card: 4242 4242 4242 4242
9// Check Dashboard → Subscriptions → [sub] → Invoices