Weave Code
Cashier Laravel Package
laravel/cashier
Laravel Cashier adds a fluent Stripe subscription billing layer to Laravel. Manage plans, trials, coupons, quantities, swaps, cancellations with grace periods, and invoicing, including PDF invoice generation, with minimal boilerplate.
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 subscriptions in my Laravel app?
- Start by requiring the package via Composer (`composer require laravel/cashier`), configuring your Stripe API keys in `.env`, and attaching the `HasSubscriptions` trait to your user model. Run the migrations to set up the required database tables, then use Cashier’s fluent API to create subscriptions (e.g., `user->newSubscription('default', 'plan_id')->create($paymentMethod)`).
- Does Laravel Cashier support plan swaps and prorated billing?
- Yes, Cashier handles plan swaps seamlessly with prorated billing. Use the `swap()` method to transition users between plans while adjusting charges for partial periods. For example, `user->subscription('default')->swap('new_plan_id')`. You can also specify quantities or trial periods during the swap.
- What Laravel versions does Cashier officially support?
- Laravel Cashier v16.x supports Laravel 13.x, while earlier versions (v15.x) cover Laravel 9.x–12.x. Check the [Laravel documentation](https://laravel.com/docs/billing) for version-specific requirements. Always ensure your Laravel version aligns with the Cashier version you’re using to avoid compatibility issues.
- How do I handle Stripe webhooks with Cashier?
- Set up a `/stripe/webhook` route in your `routes/web.php` or `routes/api.php` and protect it with the `VerifyWebhookSignature` middleware. Cashier automatically maps webhook events to Laravel events (e.g., `invoice.paid` triggers `invoice.paid`). Queue webhook handlers for performance, especially in high-traffic applications.
- Can I generate invoice PDFs for customers using Cashier?
- Yes, Cashier provides a `downloadInvoice()` method to generate PDF invoices for subscriptions. For example, `user->subscription('default')->downloadInvoice()`. This leverages Stripe’s invoice data and formats it into a downloadable PDF. Ensure your server has the required PHP extensions (e.g., `dom`, `fileinfo`) for PDF generation.
- How do I test Cashier’s subscription logic locally?
- Use the `stripe/stripe-php` package’s test helpers or `StripeMock` to simulate Stripe API responses. Cashier’s events and methods can be tested by mocking the `Stripe` facade or using Laravel’s HTTP testing tools. For webhooks, test with the Stripe CLI (`stripe listen --forward-to localhost:3000/stripe/webhook`) to validate event handling.
- What happens if a user cancels a subscription during a grace period?
- Cashier respects Stripe’s cancellation grace period settings. When a user cancels, their subscription remains active until the grace period expires, and they retain access to the service. You can configure grace periods via Stripe’s dashboard or Cashier’s `cancel()` method with the `at_period_end` option (e.g., `user->subscription('default')->cancel()`).
- Are there alternatives to Laravel Cashier for Stripe subscriptions?
- While Cashier is Laravel’s official solution, alternatives include direct Stripe SDK integration or third-party packages like `spatie/cashier` (for multi-payment-gateway support) or `billeo/billeo` (for more complex billing logic). However, Cashier is optimized for Laravel’s ecosystem, offering deeper integration with Eloquent, events, and queues.
- How do I handle failed payments or retries in Cashier?
- Cashier automatically retries failed payments (up to Stripe’s default limits) and triggers events like `subscription.payment_failed`. Listen for these events to notify users or log failures. You can also configure custom retry logic via Stripe’s webhooks or Cashier’s `failedPayment` event observer.
- Does Cashier support multi-tenancy with separate Stripe accounts?
- Cashier does not natively support multi-tenancy with separate Stripe accounts per tenant. You’ll need to manually manage Stripe API keys and webhook endpoints for each tenant or use a middleware to switch contexts. Consider using Cashier’s events to sync subscription data across tenants if needed.
Weaver
How can I help you explore Laravel packages today?