Laravel Cashier: A Guide to Subscription Billing and Invoicing

Managing subscription billing and invoicing can be a complex and time-consuming task for any business. With the growth of software-as-a-service (SaaS) models and the increasing demand for subscription-based products, it is essential to have an efficient and reliable billing system in place. That’s where Laravel Cashier comes in.

Laravel Cashier is a popular open-source package that simplifies the management of subscription billing and invoicing for Laravel applications. In this blog post, we will discuss what Laravel Cashier is, its key features, and how to integrate it into your Laravel application. Let’s dive in!

What is Laravel Cashier?

Laravel Cashier is an official Laravel package designed to simplify the handling of subscription billing and invoicing. It provides a clean and straightforward interface for managing subscription-based services, making it easy to handle recurring payments, generate invoices, apply discounts, and manage refunds.

Laravel Cashier supports multiple payment gateways, including Stripe and Paddle, allowing developers to choose the most suitable gateway for their needs. It also comes with a set of pre-built components for common billing scenarios, such as free trials, coupons, and proration.

Key Features of Laravel Cashier

1. Simple Subscription Management: Laravel Cashier allows developers to manage subscriptions easily, including creating, updating, and canceling subscriptions. It also supports multiple subscription plans and can handle plan changes and upgrades.
2. Automatic Invoicing: Laravel Cashier generates invoices automatically for each billing cycle, ensuring your customers receive accurate and professional invoices on time. You can also customize the invoice template to match your brand’s look and feel.
3. Coupons and Discounts: Laravel Cashier supports the creation and management of coupons and discounts, making it easy to offer promotions and special deals to your customers.
4. Proration: Proration is an essential feature for subscription billing, allowing customers to switch plans and pay only for the portion of the new plan they use. Laravel Cashier handles proration seamlessly, ensuring accurate billing when customers change their subscription plans.
5. Webhooks: Laravel Cashier supports webhooks to keep your application up-to-date with any changes in your customers’ subscription statuses. This allows you to automate essential tasks, such as sending email notifications or updating user roles based on subscription status.

Integrating Laravel Cashier into Your Application

Before diving into the integration, make sure you meet the following prerequisites:

1. Laravel application with version 5.8 or later
2. Stripe or Paddle account
3. Composer installed on your local machine

Follow these steps to integrate Laravel Cashier into your application:

Step 1: Install Laravel Cashier

To install Laravel Cashier, run the following command in your terminal:

composer require laravel/cashier

Step 2: Configure Cashier

Publish the Cashier configuration file and migration by running:

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

Update your .env file with your Stripe or Paddle API keys:

STRIPE_KEY=your_stripe_key
STRIPE_SECRET=your_stripe_secret

or

PADDLE_VENDOR_ID=your_paddle_vendor_id
PADDLE_VENDOR_AUTH_CODE=your_paddle_vendor_auth_code

Step 3: Prepare User Model

Add the Billable trait to your User model:

use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

Step 4: Run Migrations

Migrate your database to create the necessary tables:

php artisan migrate

Step 5: Create Subscription Plans

Before you can start creating subscriptions, you need to set up subscription plans in your payment gateway (Stripe or Paddle). Make a note of the plan identifiers, as you’ll need them in your application.

Step 6: Implementing Subscriptions

To create a new subscription for a user, use the newSubscription method:

$user = Auth::user();
$planId = 'your_plan_identifier';

$user->newSubscription('main', $planId)->create($paymentMethod);

To cancel a subscription, call the cancel method:

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

To resume a canceled subscription, use the resume method:

$user->subscription('main')->resume($paymentMethod);

Step 7: Handling Webhooks

Configure your payment gateway to send webhook events to your application’s endpoint. For example, in Stripe, you can set the webhook URL to https://your-app-url.com/stripe/webhook.

Next, define the webhook route in your routes/web.php file:

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

Create the WebhookController and extend it from the Cashier controller:

use Laravel\Cashier\Http\Controllers\WebhookController as CashierController;

class WebhookController extends CashierController
{
    // Add your custom webhook handling logic here
}

Step 8: Customizing Invoices

To customize the invoice template, publish the Cashier views:

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

Then, you can edit the resources/views/vendor/cashier/invoice.blade.php file to match your branding.

Conclusion

Laravel Cashier is a powerful tool for managing subscription billing and invoicing in your Laravel application. With its simple API and comprehensive features, you can quickly implement subscription-based services, generate invoices, and manage billing events.

By following this guide, you should now have a solid understanding of Laravel Cashier’s capabilities and how to integrate it into your application. As your business grows, Laravel Cashier will continue to be a reliable solution for managing your subscription billing needs.