Subscription Management with Laravel Cashier: Simplified Guide

Laravel Cashier provides an efficient way to handle subscription billing for SaaS applications, specifically designed to integrate seamlessly with Stripe and Braintree. Here’s a streamlined guide to manage subscriptions effectively using Laravel Cashier.

Why Use Laravel Cashier?

Laravel Cashier handles complex billing functionalities that would typically require custom solutions, such as:

• Subscription creation and plan management
• Trial periods and grace periods
• Invoice generation and download
• Easy payment method handling
• Prorated charges for plan upgrades and downgrades

Let’s dive into how you can set up and use Laravel Cashier to manage subscriptions in your Laravel app.

Managing Subscriptions in Laravel Cashier

1. Installation and Initial Setup

To set up subscription management with Laravel Cashier, start by installing it along with moneyphp/money via Composer. Configure Stripe or Paddle API keys in the .env file for payment processing. Publish the Cashier configuration, define your subscription plans, and run migrations to create billing tables. Add the Billable trait to your User model to enable subscription features.

2. Setup the User Model

The Billable trait on your User model enables billing-related methods:

use Laravel\Cashier\Billable;
class User extends Authenticatable
{
    use Billable;
}

3. Creating Subscriptions

To create a subscription, link the user to a plan with newSubscription and specify a payment method (using Stripe’s payment method ID):

$user = User::find(1);
$user->newSubscription('default', 'premium')->create($paymentMethod);

Optional Parameters

Trial Periods: To include a free trial, you can pass a trial period:

$user->newSubscription('default', 'premium')
->trialDays(14)
->create($paymentMethod);

4. Managing Subscription Status

Cashier provides methods to handle subscription states, including checking, canceling, and resuming subscriptions:

Check Active Subscription:

if ($user->subscribed('default')) {
    // User is subscribed
}

Cancel Subscription at End of Period:

$user->subscription('default')->cancel();

Cancel Immediately:

$user->subscription('default')->cancelNow();

Resume Subscription (within grace period):

$user->subscription('default')->resume();

5. Switching Subscription Plans

Cashier allows users to change plans easily:

Upgrade/Downgrade Plan:

$user->subscription('default')->swap('new-plan-id');

Swap with Immediate Billing:

$user->subscription('default')->swapAndInvoice('new-plan-id');

6. Handling Single Charges

For one-time charges, use the charge method, which requires an amount in cents (e.g., 1000 = $10.00 if currency is USD):

$user->charge(1000, 'payment_method_id');

7. Invoices and Receipts

Cashier automatically generates invoices for charges. Users can view/download invoices:

Retrieve Specific Invoice:

$invoice = $user->findInvoice($invoiceId);
return $invoice->download();

View All Invoices:

$invoices = $user->invoices();

8. Handling Payment Methods

Cashier makes it easy to manage user payment methods with Stripe:

Add Payment Method:

$user->addPaymentMethod($paymentMethod);

Update Default Payment Method:

$user->updateDefaultPaymentMethod($newPaymentMethod);

Delete All Payment Methods:

$user->deletePaymentMethods();

9. Webhooks for Real-Time Event Handling

Cashier provides default routes for handling Stripe webhooks to manage subscription lifecycle events, such as failed payments or canceled subscriptions.

Run cashier:webhook to register the webhook route:

php artisan cashier:webhook

Then configure the webhook URL in Stripe to point to this endpoint (e.g., https://yourapp.com/stripe/webhook).

10. Prorating and Seat-Based Billing

• Prorating Plan Swaps: Cashier automatically calculates prorated charges for users who change plans mid-cycle.

Seat-Based Billing: Adjust the quantity of a subscription (for example, to bill per user seat).

$user->subscription('default')->incrementQuantity();
$user->subscription('default')->decrementQuantity();

Example Workflow for Creating and Managing Subscriptions

Below is a typical example of how Cashier simplifies managing a subscription in a Laravel controller:

public function subscribeUser(Request $request)
{
    $user = auth()->user();
    // Attach a payment method and create subscription
    $user->newSubscription('default', 'premium-plan')
         ->trialDays(14)
         ->create($request->paymentMethod);
    return response()->json(['message' => 'Subscription created successfully.']);
}
public function cancelSubscription()
{
    $user = auth()->user();
    // Cancel subscription at end of period
    $user->subscription('default')->cancel();
    return response()->json(['message' => 'Subscription canceled.']);
}

Laravel Cashier streamlines the complex aspects of subscription billing, making it straightforward to integrate payment handling, subscription lifecycle management, and billing in a Laravel app.

FAQs on Laravel Cashier for Subscription Management

Conclusion

Laravel Cashier is the ideal choice for simplifying subscription billing in your Laravel application. It manages all aspects of billing, including proration, trial periods, and payment methods, making it easier to build a seamless subscription experience for your users. Whether you’re launching a new subscription platform or enhancing an existing one, Cashier is a reliable solution to streamline your billing process.

Ready to get started? Hire a Laravel developer today to unlock the full potential of Laravel Cashier in your application!