Upgrade and Downgrade Subscriptions using Laravel & stripe-php

Upgrading and downgrading subscriptions is a common feature in applications that offer subscription-based services. In this tutorial, we'll learn how to implement this functionality in a Laravel application using the Stripe PHP SDK.

This tutorial assumes you have a basic understanding of Laravel and have a Stripe account set up. If you're new to Stripe, consider reviewing the official Stripe documentation before proceeding.

Prerequisites

Laravel installed on your system.
A Stripe account with test API keys.
The stripe-php package installed via Composer.

Setting Up Stripe in Laravel

First, install the Stripe PHP library using Composer:

composer require stripe/stripe-php

Next, configure your Stripe API keys. You can set them in your .env file:

STRIPE_KEY=your_stripe_publishable_key
STRIPE_SECRET=your_stripe_secret_key

And then add them to your config/services.php file:

'stripe' => [
    'key' => env('STRIPE_KEY'),
    'secret' => env('STRIPE_SECRET'),
],

Retrieving the Subscription and Items

To upgrade or downgrade a subscription, you first need to retrieve the subscription and its items:

\Stripe\Stripe::setApiKey(config('services.stripe.secret'));
 
$subscriptionId = 'sub_XXXXXXXXXXXX';
 
$subscription = \Stripe\Subscription::retrieve($subscriptionId);
 
$subscriptionItemId = $subscription->items->data[0]->id;

Upgrading or Downgrading the Subscription

You can update the subscription by changing the price associated with the subscription item. Make sure to specify the id of the subscription item and the new price_id:

$newPriceId = 'price_YYYYYYYYYYYYYY';
 
$updatedSubscription = \Stripe\Subscription::update($subscriptionId, [
    'items' => [
        [
            'id' => $subscriptionItemId,
            'price' => $newPriceId,
        ],
    ],
]);

This replaces the current price with the new one. If you don't specify the id of the subscription item, Stripe will add the new price as an additional item, resulting in both prices being active.

Handling Quantities

If your subscription uses quantities, you need to preserve the existing quantity when updating:

$quantity = $subscription->items->data[0]->quantity;
 
$updatedSubscription = \Stripe\Subscription::update($subscriptionId, [
    'items' => [
        [
            'id' => $subscriptionItemId,
            'price' => $newPriceId,
            'quantity' => $quantity,
        ],
    ],
]);

Proration and Billing

By default, Stripe applies prorations when you change a customer's subscription. If you want to disable prorations, you can set the proration_behavior parameter to none:

$updatedSubscription = \Stripe\Subscription::update($subscriptionId, [
    'items' => [
        [
            'id' => $subscriptionItemId,
            'price' => $newPriceId,
        ],
    ],
    'proration_behavior' => 'none',
]);

Alternatively, to preview the upcoming invoice, you can use:

$upcomingInvoice = \Stripe\Invoice::upcoming([
    'customer' => $subscription->customer,
    'subscription' => $subscriptionId,
    'subscription_items' => [
        [
            'id' => $subscriptionItemId,
            'price' => $newPriceId,
        ],
    ],
]);

Conclusion

In this tutorial, we've learned how to upgrade and downgrade subscriptions in a Laravel application using the Stripe PHP SDK. Remember to always test your changes in a test environment before deploying to production.

For more information, refer to the Stripe Subscriptions Documentation.