Weave Code
Cashier Laravel Package
laravel/cashier
Laravel Cashier (Stripe) adds a fluent, expressive API for subscription billing in Laravel. Manage subscriptions, coupons, plan swaps, quantities, cancellation grace periods, and invoice PDF generation—without writing boilerplate billing code.
Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.
Frequently asked questions about Cashier
- How do I integrate Laravel Cashier with Stripe for subscriptions in a Laravel 11 app?
- First, install Cashier via Composer: `composer require laravel/cashier`. Publish the config with `php artisan vendor:publish --tag=cashier-config`, then set your Stripe keys in `.env`. Add the `HasCustomer` and `HasSubscription` traits to your user model, run migrations (`php artisan migrate`), and configure a Stripe webhook endpoint (e.g., `/stripe/webhooks`). The official Laravel docs provide step-by-step setup instructions.
- Does Laravel Cashier support coupon codes for subscriptions?
- Yes, Cashier fully supports Stripe coupons. You can apply coupons when creating subscriptions using the `withCoupon()` method, e.g., `$user->newSubscription('main', 'plan_id')->withCoupon('SUMMER20')->create()`. Cashier also handles coupon expiration and percentage/amount discounts seamlessly. Check the [Laravel Billing docs](https://laravel.com/docs/billing#coupons) for advanced usage.
- Can I generate invoice PDFs with Laravel Cashier?
- Absolutely. Cashier includes built-in invoice PDF generation via DomPDF. Use the `invoice()` method on a subscription, e.g., `$invoice = $user->subscription('main')->invoice();`, then pass the invoice object to a view or download it directly. Customize invoice templates by publishing Cashier’s views with `php artisan vendor:publish --tag=cashier-views`.
- What Laravel versions does Cashier v16.x support?
- Cashier v16.x supports Laravel 10, 11, 12, and 13 (LTS versions). It requires PHP 8.1–8.5. For Laravel 9.x, use Cashier v15.x. Always check the [Packagist page](https://packagist.org/packages/laravel/cashier) for version-specific compatibility notes. The package follows Laravel’s release cycle closely, ensuring long-term support.
- How do I handle Stripe webhook events in Laravel Cashier?
- Cashier includes middleware (`VerifyWebhookSignature`) to validate Stripe webhooks. Define a route like `Route::post('/stripe/webhooks', [StripeWebhookController::class, 'handle'])->middleware('signed');`. Use the `HandleWebhook` middleware to automatically process events (e.g., `customer.subscription.created`). For custom logic, extend the `HandleWebhook` class or create event listeners.
- Can I swap a user’s subscription plan mid-term with proration?
- Yes, Cashier handles plan swaps with proration automatically. Use the `swap()` method, e.g., `$user->subscription('main')->swap('new_plan_id')`. Cashier calculates prorated charges based on the subscription’s billing cycle and updates Stripe accordingly. This works for both monthly and annual plans. Refer to the [proration docs](https://laravel.com/docs/billing#subscription-plan-swaps) for edge cases.
- Is Laravel Cashier suitable for multi-currency billing?
- Cashier itself doesn’t natively support multi-currency billing, as Stripe’s subscription model is primarily USD-centric. However, you can use Stripe’s [prices API](https://stripe.com/docs/api/prices) with Cashier to create multi-currency products and manually handle conversions in your application. For advanced multi-currency needs, consider third-party solutions like [Paddle](https://paddle.com/) with `laravel/cashier-paddle`.
- How do I test Cashier’s subscription logic in Laravel?
- Use Stripe’s test mode (keys in `.env`) and Cashier’s built-in testing helpers. Mock Stripe responses with `Stripe::shouldReceive()` in PHPUnit or use `Stripe::fake()` to simulate events. Test webhooks by triggering events via `Stripe::trigger()` or by sending test payloads to your webhook endpoint. Cashier’s tests in the [GitHub repo](https://github.com/laravel/cashier/tree/master/tests) serve as a reference for common scenarios.
- What are the alternatives to Laravel Cashier for Stripe subscriptions?
- Alternatives include `spatie/laravel-billing` (supports multiple gateways like PayPal), `filamentphp/filament-billing` (for Filament admin panels), or raw Stripe SDK integration. Cashier is the most Laravel-native option, offering deep integration with Eloquent, migrations, and Laravel’s ecosystem. If you need multi-gateway support, `spatie/laravel-billing` is a strong alternative, though it lacks Cashier’s polished API.
- How do I handle failed payments or dunning in Laravel Cashier?
- Cashier integrates with Stripe’s dunning features. When a payment fails, Stripe automatically retries (default: 3 times). Use the `failed()` method to check subscription status, e.g., `if ($user->subscription('main')->failed())`. For custom dunning logic (e.g., email reminders), listen to `customer.subscription.deleted` webhook events or extend Cashier’s behavior with middleware. Stripe’s [dunning guide](https://stripe.com/docs/billing/dunning) provides best practices.
Weaver
How can I help you explore Laravel packages today?