How to Set Up Laravel Cashier? Complete Guide

Managing subscriptions, recurring payments, and invoicing can be a hassle for any subscription-based business. But with Laravel Cashier, you can simplify it all. This powerful package seamlessly integrates with payment gateways like Stripe, automating everything from setting up subscriptions to handling proration, trial periods, and even single charges.

Laravel Cashier simplifies subscription management, whether you’re building a new platform or upgrading an existing one. It handles everything from integrating with Stripe to managing proration, trials, and one-time charges, making billing more efficient and hassle-free.

Let’s explore how to set up and use Laravel Cashier with our Laravel development services for seamless subscription management!

What is Laravel Cashier?

Laravel Cashier is an official package for the Laravel PHP framework that simplifies and streamlines the process of managing subscription billing and invoicing for your web application. It essentially acts as a bridge between your Laravel app and a secure payment gateway, like Stripe, to handle all the nitty-gritty of recurring payments.

With Cashier, Laravel development experts can easily handle coupon redemptions, subscription quantity changes, cancellation grace periods, and even generate invoice PDFs. This package simplifies the integration of subscription billing services into a Laravel application. So they can focus on creating unique subscription-based products rather than the complexities of billing systems.

How does Laravel Cashier Work?

Laravel Cashier is a powerful subscription billing management system that simplifies the process of handling user subscriptions and managing payment methods. Let’s see how Laravel Cashier works:

Set Up the Database

When you first install Laravel Cashier, it brings along its own set of database migrations that need to be run to create the tables necessary for storing your subscription data. 

Creating Subscription Plans

Creating subscription plans is the most important part of your recurring revenue engine, and Laravel Cashier makes it a breeze

Handling User Subscriptions

After you have created different subscription plans, the subscribers will start to pour in. But the Laravel Cashier will help you manage your journey flawlessly.

Managing Payment Methods

You have to give your users different payment methods to ensure they can pay for your subscription securely and efficiently. 

Laravel development services use Cashier to take care of the complex logic behind subscription billing. That leaves you free to focus on building a fantastic user experience and growing your business.

How to setup Laravel Cashier?

Laravel Cashier is a package designed to handle subscription billing services like Stripe and Braintree, making it easier to implement payment processing, subscription plans, and other billing-related tasks in a Laravel application. Here’s an overview of how it works and some of its key features:

1. Prerequisites for Laravel Cashier

Install this package before installing laravel cashier. 

composer require moneyphp/money

It will set up the laravel asset for the laravel cashier. 

Note: For installing the moneyphp/money make sure you have install this dependency php-bcmath or if alreday there than in php.ini file this package is enable

2. Installation, Configuration and Migration:

Install Cashier: Cashier can be installed using Composer.

composer require laravel/cashier

Setup Configuration: You’ll need to configure your .env file with your Stripe or Braintree API keys, and Cashier will use these credentials to communicate with your payment provider.

Cachiar Configuration: Cashier can be config setup using artisan.

php artisan vendor:publish --tag="cashier-config"

Once the configuration file is published, open it (located at config/cashier.php) and locate the plans section. Add your subscription plans, specifying the plan’s identifier, name, and price. Here’s an example with two plans, ‘basic’ and ‘premium’:

'plans' => [
    'basic' => [
        'name' => 'Basic Plan',
        'price' => 10.00,
    ],
    'premium' => [
        'name' => 'Premium Plan',
        'price' => 20.00,
    ],
],

Migration: Run migrations to add necessary billing columns to the users table, Like: subscription_type, billing_cycle, auto_billing, etc.

php artisan migrate

3. Defining in User Model Setup

Cashier provides billing functionality on an Eloquent model, usually User. To enable this, the model needs to use the Billable trait.

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

This trait adds methods to handle subscriptions, single charges, and other billing operations.

4. Subscription Billing

Creating a Subscription: You can create a subscription by calling the newSubscription method on the billable mode

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

Trial Periods: Cashier allows for trial periods, where you can define trial durations or start dates for each subscription.

if ($user->subscription('default')->onTrial()) { 
   // User is on trial 
}

Proration: If users switch plans mid-billing cycle, Cashier will automatically handle proration, ensuring that users are billed only for the amount used.

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

5. Payment Methods

Cashier integrates with Stripe’s setup for storing and managing payment methods. You can set up a payment method (like a card) and assign it to a customer:

$user->addPaymentMethod('payment_method_id');

6. Invoices and Receipts

Cashier makes it easy to generate invoices and receipts for transactions. For example:

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

Users can view their invoice history, and admins can generate receipts as needed.

7. Handling Failed Payments

Cashier comes with a built-in webhook that listens for payment failure events from Stripe. This webhook can trigger notifications, retry mechanisms, or suspend the subscription based on your business rules. Here you can use stribe’s suit in webhook class or create you own. 

8. Handing the Single Charges and One-Time Payments

Cashier supports single, one-time charges. This can be done using the charge method:

// 1000 = $10.00 if Stripe is set to USD
$user->charge(1000, 'payment_method_id');

9. Payment Gateway Webhooks Implementation to Handle the Payment Success, Failures, or Subscription Cancellations

To add custom functionality, extend Cashier’s WebhookController by creating a new controller:

php artisan make:controller StripeWebhookController

Then, extend WebhookController in your new controller (app/Http/Controllers/StripeWebhookController.php):

namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Laravel\Cashier\Http\Controllers\WebhookController as CashierWebhookController;
class StripeWebhookController extends CashierWebhookController
{
    /**
     * Handle the `invoice.payment_succeeded` webhook.
     *
     * @param  array  $payload
     * @return \Symfony\Component\HttpFoundation\Response
     */
    public function handleInvoicePaymentSucceeded(array $payload)
    {
        // Your custom logic for successful payments
        $invoice = $payload['data']['object'];
        // Example: Send a custom email notification
        $user = User::where('stripe_id', $invoice['customer'])->first();
        if ($user) {
            // Notify the user
            $user->notify(new PaymentSuccessNotification($invoice));
        }
        return parent::handleInvoicePaymentSucceeded($payload);
    }
    /**
     * Handle the `invoice.payment_failed` webhook.
     *
     * @param  array  $payload
     * @return \Symfony\Component\HttpFoundation\Response
     */
    public function handleInvoicePaymentFailed(array $payload)
    {
        // Your custom logic for failed payments
        $invoice = $payload['data']['object'];
        $user = User::where('stripe_id', $invoice['customer'])->first();
        if ($user) {
            // Notify the user about the failure
            $user->notify(new PaymentFailureNotification($invoice));
        }
        return parent::handleInvoicePaymentFailed($payload);
    }
    /**
     * Handle the `customer.subscription.deleted` webhook.
     *
     * @param  array  $payload
     * @return \Symfony\Component\HttpFoundation\Response
     */
    public function handleCustomerSubscriptionDeleted(array $payload)
    {
        // Custom logic for subscription cancellations
        $subscription = $payload['data']['object'];
        $user = User::where('stripe_id', $subscription['customer'])->first();
        if ($user) {
            // Notify the user about subscription cancellation
            $user->notify(new SubscriptionCancelledNotification());
        }
        return parent::handleCustomerSubscriptionDeleted($payload);
    }
}

In this example, we customize three webhooks:

1. invoice.payment_succeeded: Sends a notification when payment is successful.
2. invoice.payment_failed: Notifies the user if a payment fails.
3. customer.subscription.deleted: Notifies the user about a subscription cancellation.

Note: Ensure you have appropriate notification classes like PaymentSuccessNotification, PaymentFailureNotification, and SubscriptionCancelledNotification.

Now, update your webhook route to use the custom StripeWebhookController:

Route::post('stripe/webhook', [App\Http\Controllers\StripeWebhookController::class, 'handleWebhook']);

This tells Laravel to use your customized webhook handling controller.

Example: Subscribing a User to a Plan

Here’s a complete example of how a user might be subscribed to a plan:

$user = User::find(1); // Retrieve the user
// Attach payment method and create subscription
$user->newSubscription('default', 'plan-id')->create('payment_method_id');
// Check subscription status
if ($user->subscribed('default')) {
    // User is actively subscribed to the default plan
}

You can define this code in your relevant controller where you want to define user subscribtion and mange the billing cycle. 

Some Important function that can be useful while working with Laravel Chashier.

Laravel Cashier provides several built-in methods on models that use the Billable trait to handle subscription billing, single charges, and other billing operations. Here’s an overview of the most important ones:

1. Subscription Methods

• newSubscription($subscriptionName, $planId): Initializes a new subscription for the user.

$user->newSubscription('default', 'plan-id')->create($paymentMethod);

• subscribed($subscriptionName): Checks if the user is actively subscribed to a given plan.

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

• subscription($subscriptionName): Retrieves a specific subscription instance, which allows you to check details and perform actions.

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

• cancel(): Cancels a subscription at the end of the billing period.

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

• cancelNow(): Immediately cancels a subscription without waiting for the billing period to end.

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

• resume(): Resumes a canceled subscription if it is still within the grace period.

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

• onTrial(): Checks if a user is currently on a trial period.

if ($user->subscription('default')->onTrial()) {
    // User is on trial
}

• onGracePeriod(): Checks if a canceled subscription is still within the grace period.

if ($user->subscription('default')->onGracePeriod()) {
    // User is within grace period
}

2. Single Charge and Invoice Methods

• charge($amount, $paymentMethodId = null): Charges a one-time payment to the user.

$user->charge(1000, 'payment_method_id'); // Amount in cents (e.g., 1000 = $10.00)

• invoice(): Attempts to invoice the customer for any pending charges.

$user->invoice();

• findInvoice($invoiceId): Retrieves a specific invoice by its ID.

$invoice = $user->findInvoice('invoice-id');

• downloadInvoice($invoiceId): Downloads a specific invoice as a PDF.

return $user->downloadInvoice('invoice-id', ['vendor' => 'Your Company', 'product' => 'Your Product']);

3. Payment Method Methods

• addPaymentMethod($paymentMethodId): Adds a new payment method for the user.

$user->addPaymentMethod('payment_method_id');

• updateDefaultPaymentMethod($paymentMethodId): Updates the default payment method.

$user->updateDefaultPaymentMethod('new_payment_method_id');

• paymentMethods(): Retrieves all available payment methods for the user.

$paymentMethods = $user->paymentMethods();

• deletePaymentMethods(): Deletes all payment methods for a user.

$user->deletePaymentMethods();

4. Handling Subscription Upgrades and Downgrades

• swap($planId): Switches the user to a different subscription plan.

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

• swapAndInvoice($planId): Swaps the subscription plan and immediately invoices the user.

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

• incrementQuantity($quantity = 1): Increases the quantity of the subscription (for per-seat billing).

$user->subscription('default')->incrementQuantity(2); // Adds 2 to the current quantity

• decrementQuantity($quantity = 1): Decreases the quantity of the subscription.

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

5. Trial and Grace Period Methods

• onTrial(): Checks if the user is currently on a trial period for a specific subscription.

if ($user->subscription('default')->onTrial()) {
    // User is on a trial period
}

• onGracePeriod(): Checks if a canceled subscription is still in the grace period.

if ($user->subscription('default')->onGracePeriod()) {
    // User is in the grace period
}

These methods in Laravel Cashier allow you to handle various aspects of billing, including subscriptions, one-time charges, upgrades, and trial management. They also simplify handling payment methods and managing subscriptions directly on the user model.

FAQs Related to Laravel Cashier

To Conclude

Laravel Cashier offers a comprehensive solution for managing subscriptions, payments, and billing in your Laravel application. It simplifies everything from setting up subscriptions and handling proration to managing payment methods and generating invoices. With its seamless integration and robust features, Cashier takes the complexity out of subscription management. It allows you to focus more on enhancing your product and user experience.

If you’re looking to build or optimize your subscription-based platform, Laravel Cashier is the go-to tool. Ready to enhance your billing system? Explore its potential and ensure a seamless experience for your users with our Laravel development services!