Laravel Billing (Cashier)
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Check existing billing setup, User model
- fuse-ai-pilot:research-expert - Verify latest Cashier docs via Context7
- mcp__context7__query-docs - Query specific patterns (Stripe/Paddle)
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
Laravel Cashier provides subscription billing with Stripe or Paddle. Choose based on your needs:
| Provider |
Package |
Best For |
| Stripe |
laravel/cashier |
Full control, high volume, complex billing |
| Paddle |
laravel/cashier-paddle |
Tax handling, compliance, global sales |
Key Difference: MoR vs Payment Processor
| Aspect |
Stripe |
Paddle |
| Type |
Payment Processor |
Merchant of Record |
| Taxes |
You manage (or Stripe Tax) |
Paddle manages automatically |
| Invoices |
Your company name |
Paddle + your name |
| Compliance |
Your responsibility |
Paddle handles |
| Fees |
~2.9% + $0.30 |
~5% + $0.50 (all-inclusive) |
Critical Rules
- Use webhooks - Never rely on client-side confirmations
- Handle grace periods - Allow access until subscription ends
- Never store card details - Use payment tokens/methods
- Test with test keys - Always before production
- Verify webhook signatures - Prevent spoofing attacks
- Handle incomplete payments - 3D Secure requires user action
Architecture
app/
├── Http/
│ ├── Controllers/
│ │ └── Billing/ ← Billing controllers
│ │ ├── SubscriptionController.php
│ │ ├── CheckoutController.php
│ │ └── InvoiceController.php
│ └── Middleware/
│ └── EnsureSubscribed.php ← Subscription check
├── Models/
│ └── User.php ← Billable trait
├── Listeners/
│ └── StripeEventListener.php ← Webhook handling
└── Services/
└── BillingService.php ← Business logic
config/
├── cashier.php ← Stripe/Paddle config
└── services.php ← API keys
routes/
└── web.php ← Webhook routes (excluded from CSRF)
FuseCore Integration
When working in a FuseCore project, billing follows the modular structure:
FuseCore/
├── Core/ # Infrastructure (priority 0)
│ └── App/Contracts/
│ └── BillingServiceInterface.php ← Billing contract
│
├── User/ # Auth module (existing)
│ └── App/Models/User.php ← Add Billable trait here
│
├── Billing/ # Billing module (new)
│ ├── App/
│ │ ├── Http/
│ │ │ ├── Controllers/
│ │ │ │ ├── SubscriptionController.php
│ │ │ │ ├── CheckoutController.php
│ │ │ │ └── WebhookController.php
│ │ │ └── Middleware/
│ │ │ └── EnsureSubscribed.php
│ │ ├── Listeners/
│ │ │ └── HandleWebhookEvents.php
│ │ └── Services/
│ │ └── BillingService.php
│ ├── Config/
│ │ └── cashier.php ← Module-level config
│ ├── Database/Migrations/
│ ├── Routes/
│ │ ├── web.php ← Webhooks (no CSRF)
│ │ └── api.php ← Subscription management
│ └── module.json # dependencies: ["User"]
FuseCore Billing Checklist
→ See fusecore skill for complete module patterns.
Decision Guide
Stripe vs Paddle
Selling to businesses (B2B)? → Stripe
├── Need OAuth for third-party apps? → Stripe Connect
└── Selling to consumers (B2C) globally?
├── Want to handle taxes yourself? → Stripe + Stripe Tax
└── Want tax compliance handled? → Paddle
Subscription vs One-Time
Recurring revenue? → Subscription
├── Fixed plans? → Single-price subscription
└── Usage-based? → Metered billing (Stripe) or quantity-based
Single purchase? → One-time charge
├── Digital product? → Checkout session
└── Service fee? → Direct charge
Key Concepts
| Concept |
Description |
Reference |
| Billable |
Trait that enables billing on a model |
stripe.md |
| Subscription |
Recurring billing cycle |
subscriptions.md |
| Price ID |
Stripe/Paddle price identifier |
stripe.md |
| Grace Period |
Time after cancellation with access |
subscriptions.md |
| Webhook |
Server-to-server payment notifications |
webhooks.md |
| Customer Portal |
Self-service billing management |
checkout.md |
Reference Guide
Concepts (WHY & Architecture)
| Topic |
Reference |
When to Consult |
| Stripe Cashier |
stripe.md |
Stripe setup, configuration |
| Paddle Cashier |
paddle.md |
Paddle setup, differences |
| Subscriptions |
subscriptions.md |
Create, cancel, swap, pause |
| Webhooks |
webhooks.md |
Webhook security, handling |
| Invoices |
invoices.md |
PDF generation, receipts |
| Payment Methods |
payment-methods.md |
Cards, wallets, updates |
| Checkout |
checkout.md |
Hosted checkout, portal |
| Testing |
testing.md |
Test cards, webhook testing |
Advanced SaaS Features
| Topic |
Reference |
When to Consult |
| Metered Billing |
metered-billing.md |
Usage-based pricing (API, storage) |
| Team Billing |
team-billing.md |
Organization billing, per-seat |
| Dunning |
dunning.md |
Failed payment recovery |
| Feature Flags |
feature-flags.md |
Plan-based feature access |
Templates (Complete Code)
| Template |
When to Use |
| UserBillable.php.md |
User model with Billable trait |
| SubscriptionController.php.md |
CRUD subscription operations |
| WebhookController.php.md |
Custom webhook handling |
| CheckoutController.php.md |
Stripe Checkout + Portal |
| InvoiceController.php.md |
Invoice download |
| BillingRoutes.php.md |
Complete route definitions |
| SubscriptionTest.php.md |
Pest tests for billing |
| MeteredBillingController.php.md |
Usage tracking and reporting |
| TeamBillable.php.md |
Team model with seat management |
| DunningService.php.md |
Payment recovery automation |
| FeatureFlags.php.md |
Laravel Pennant per-plan features |
Quick Reference
Check Subscription Status
// Has active subscription?
$user->subscribed('default');
// Subscribed to specific price?
$user->subscribedToPrice('price_premium', 'default');
// On trial?
$user->onTrial('default');
// Cancelled but still active?
$user->subscription('default')->onGracePeriod();
Create Subscription
// Simple subscription
$user->newSubscription('default', 'price_monthly')
->create($paymentMethodId);
// With trial
$user->newSubscription('default', 'price_monthly')
->trialDays(14)
->create($paymentMethodId);
Manage Subscription
$subscription = $user->subscription('default');
// Change plan
$subscription->swap('price_yearly');
// Cancel at period end
$subscription->cancel();
// Cancel immediately
$subscription->cancelNow();
// Resume cancelled subscription
$subscription->resume();
Billing Portal
// Redirect to customer portal (Stripe)
return $user->redirectToBillingPortal(route('dashboard'));
// Get portal URL
$url = $user->billingPortalUrl(route('dashboard'));
Best Practices
DO
- Use webhooks for payment confirmation
- Implement grace periods for cancelled subscriptions
- Set up webhook signature verification
- Handle
IncompletePayment exceptions
- Test with Stripe CLI locally
- Prune old data regularly
DON'T
- Trust client-side payment confirmations
- Store card numbers (PCI compliance)
- Skip webhook verification
- Ignore failed payment webhooks
- Forget to handle 3D Secure
- Hardcode prices (use env or config)
Laravel 13 Notes
Cashier Stripe 16.x et Cashier Paddle 2.x sont compatibles Laravel 13. Points d'attention :
- Webhooks : la nouvelle protection CSRF [[laravel-auth]]
PreventRequestForgery doit exclure les routes webhook (stripe/webhook, paddle/webhook) via validateOrigin(except: [...])
serializable_classes : whitelister les DTOs Cashier si vous serialize des subscriptions (queue)
- PHP 8.3 minimum : Cashier 16.x supporte 8.3+ uniquement
// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
$middleware->validateOrigin(except: [
'stripe/*', 'paddle/*',
]);
})
1---2name: laravel-billing3description: Use when implementing subscriptions, invoices, payment methods, webhooks, or billing portals with Laravel Cashier (Stripe or Paddle).4versions:5 laravel: "13.0"6 cashier-stripe: "16.x"7 cashier-paddle: "2.x"8 php: "8.3"9user-invocable: true10references: references/stripe.md, references/paddle.md, references/subscriptions.md, references/webhooks.md, references/invoices.md, references/payment-methods.md, references/testing.md, references/checkout.md, references/metered-billing.md, references/team-billing.md, references/dunning.md, references/feature-flags.md, references/templates/UserBillable.php.md, references/templates/SubscriptionController.php.md, references/templates/WebhookController.php.md, references/templates/CheckoutController.php.md, references/templates/InvoiceController.php.md, references/templates/BillingRoutes.php.md, references/templates/SubscriptionTest.php.md, references/templates/MeteredBillingController.php.md, references/templates/TeamBillable.php.md, references/templates/DunningService.php.md, references/templates/FeatureFlags.php.md11related-skills: laravel-auth, laravel-api, fusecore12metadata:13 source: https://skillmd.com/skills/fusengine/laravel-billing14---1516<objective>17Covers Laravel Cashier for Stripe and Paddle: choosing between the two18(payment processor vs merchant-of-record, tax handling, fees), subscription19lifecycle (create, swap, cancel, resume, trials, grace periods), webhooks and20signature verification, invoices, payment methods, checkout/customer portal,21metered/usage-based billing, team/per-seat billing, dunning (failed-payment22recovery), and Pennant-based feature flags per plan. Includes FuseCore23modular-project integration. For multi-vendor/marketplace split payments, see24laravel-stripe-connect instead.25</objective>2627# Laravel Billing (Cashier)2829## Agent Workflow (MANDATORY)3031Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:32331. **fuse-ai-pilot:explore-codebase** - Check existing billing setup, User model342. **fuse-ai-pilot:research-expert** - Verify latest Cashier docs via Context7353. **mcp__context7__query-docs** - Query specific patterns (Stripe/Paddle)3637After implementation, run **fuse-ai-pilot:sniper** for validation.3839---4041## Overview4243Laravel Cashier provides subscription billing with Stripe or Paddle. Choose based on your needs:4445| Provider | Package | Best For |46|----------|---------|----------|47| **Stripe** | `laravel/cashier` | Full control, high volume, complex billing |48| **Paddle** | `laravel/cashier-paddle` | Tax handling, compliance, global sales |4950### Key Difference: MoR vs Payment Processor5152| Aspect | Stripe | Paddle |53|--------|--------|--------|54| **Type** | Payment Processor | Merchant of Record |55| **Taxes** | You manage (or Stripe Tax) | Paddle manages automatically |56| **Invoices** | Your company name | Paddle + your name |57| **Compliance** | Your responsibility | Paddle handles |58| **Fees** | ~2.9% + $0.30 | ~5% + $0.50 (all-inclusive) |5960---6162## Critical Rules63641. **Use webhooks** - Never rely on client-side confirmations652. **Handle grace periods** - Allow access until subscription ends663. **Never store card details** - Use payment tokens/methods674. **Test with test keys** - Always before production685. **Verify webhook signatures** - Prevent spoofing attacks696. **Handle incomplete payments** - 3D Secure requires user action7071---7273## Architecture7475```76app/77├── Http/78│ ├── Controllers/79│ │ └── Billing/ ← Billing controllers80│ │ ├── SubscriptionController.php81│ │ ├── CheckoutController.php82│ │ └── InvoiceController.php83│ └── Middleware/84│ └── EnsureSubscribed.php ← Subscription check85├── Models/86│ └── User.php ← Billable trait87├── Listeners/88│ └── StripeEventListener.php ← Webhook handling89└── Services/90 └── BillingService.php ← Business logic9192config/93├── cashier.php ← Stripe/Paddle config94└── services.php ← API keys9596routes/97└── web.php ← Webhook routes (excluded from CSRF)98```99100---101102## FuseCore Integration103104When working in a **FuseCore project**, billing follows the modular structure:105106```107FuseCore/108├── Core/ # Infrastructure (priority 0)109│ └── App/Contracts/110│ └── BillingServiceInterface.php ← Billing contract111│112├── User/ # Auth module (existing)113│ └── App/Models/User.php ← Add Billable trait here114│115├── Billing/ # Billing module (new)116│ ├── App/117│ │ ├── Http/118│ │ │ ├── Controllers/119│ │ │ │ ├── SubscriptionController.php120│ │ │ │ ├── CheckoutController.php121│ │ │ │ └── WebhookController.php122│ │ │ └── Middleware/123│ │ │ └── EnsureSubscribed.php124│ │ ├── Listeners/125│ │ │ └── HandleWebhookEvents.php126│ │ └── Services/127│ │ └── BillingService.php128│ ├── Config/129│ │ └── cashier.php ← Module-level config130│ ├── Database/Migrations/131│ ├── Routes/132│ │ ├── web.php ← Webhooks (no CSRF)133│ │ └── api.php ← Subscription management134│ └── module.json # dependencies: ["User"]135```136137### FuseCore Billing Checklist138139- [ ] Billing code in `/FuseCore/Billing/` module140- [ ] Billable trait on User model in `/FuseCore/User/`141- [ ] Webhook routes in `/FuseCore/Billing/Routes/web.php`142- [ ] Exclude webhook from CSRF in `VerifyCsrfToken`143- [ ] Declare `"User"` dependency in `module.json`144145→ See [fusecore skill](../fusecore/SKILL.md) for complete module patterns.146147---148149## Decision Guide150151### Stripe vs Paddle152153```154Selling to businesses (B2B)? → Stripe155├── Need OAuth for third-party apps? → Stripe Connect156└── Selling to consumers (B2C) globally?157 ├── Want to handle taxes yourself? → Stripe + Stripe Tax158 └── Want tax compliance handled? → Paddle159```160161### Subscription vs One-Time162163```164Recurring revenue? → Subscription165├── Fixed plans? → Single-price subscription166└── Usage-based? → Metered billing (Stripe) or quantity-based167Single purchase? → One-time charge168├── Digital product? → Checkout session169└── Service fee? → Direct charge170```171172---173174## Key Concepts175176| Concept | Description | Reference |177|---------|-------------|-----------|178| **Billable** | Trait that enables billing on a model | [stripe.md](references/stripe.md) |179| **Subscription** | Recurring billing cycle | [subscriptions.md](references/subscriptions.md) |180| **Price ID** | Stripe/Paddle price identifier | [stripe.md](references/stripe.md) |181| **Grace Period** | Time after cancellation with access | [subscriptions.md](references/subscriptions.md) |182| **Webhook** | Server-to-server payment notifications | [webhooks.md](references/webhooks.md) |183| **Customer Portal** | Self-service billing management | [checkout.md](references/checkout.md) |184185---186187## Reference Guide188189### Concepts (WHY & Architecture)190191| Topic | Reference | When to Consult |192|-------|-----------|-----------------|193| **Stripe Cashier** | [stripe.md](references/stripe.md) | Stripe setup, configuration |194| **Paddle Cashier** | [paddle.md](references/paddle.md) | Paddle setup, differences |195| **Subscriptions** | [subscriptions.md](references/subscriptions.md) | Create, cancel, swap, pause |196| **Webhooks** | [webhooks.md](references/webhooks.md) | Webhook security, handling |197| **Invoices** | [invoices.md](references/invoices.md) | PDF generation, receipts |198| **Payment Methods** | [payment-methods.md](references/payment-methods.md) | Cards, wallets, updates |199| **Checkout** | [checkout.md](references/checkout.md) | Hosted checkout, portal |200| **Testing** | [testing.md](references/testing.md) | Test cards, webhook testing |201202### Advanced SaaS Features203204| Topic | Reference | When to Consult |205|-------|-----------|-----------------|206| **Metered Billing** | [metered-billing.md](references/metered-billing.md) | Usage-based pricing (API, storage) |207| **Team Billing** | [team-billing.md](references/team-billing.md) | Organization billing, per-seat |208| **Dunning** | [dunning.md](references/dunning.md) | Failed payment recovery |209| **Feature Flags** | [feature-flags.md](references/feature-flags.md) | Plan-based feature access |210211### Templates (Complete Code)212213| Template | When to Use |214|----------|-------------|215| [UserBillable.php.md](references/templates/UserBillable.php.md) | User model with Billable trait |216| [SubscriptionController.php.md](references/templates/SubscriptionController.php.md) | CRUD subscription operations |217| [WebhookController.php.md](references/templates/WebhookController.php.md) | Custom webhook handling |218| [CheckoutController.php.md](references/templates/CheckoutController.php.md) | Stripe Checkout + Portal |219| [InvoiceController.php.md](references/templates/InvoiceController.php.md) | Invoice download |220| [BillingRoutes.php.md](references/templates/BillingRoutes.php.md) | Complete route definitions |221| [SubscriptionTest.php.md](references/templates/SubscriptionTest.php.md) | Pest tests for billing |222| [MeteredBillingController.php.md](references/templates/MeteredBillingController.php.md) | Usage tracking and reporting |223| [TeamBillable.php.md](references/templates/TeamBillable.php.md) | Team model with seat management |224| [DunningService.php.md](references/templates/DunningService.php.md) | Payment recovery automation |225| [FeatureFlags.php.md](references/templates/FeatureFlags.php.md) | Laravel Pennant per-plan features |226227---228229## Quick Reference230231### Check Subscription Status232233```php234// Has active subscription?235$user->subscribed('default');236237// Subscribed to specific price?238$user->subscribedToPrice('price_premium', 'default');239240// On trial?241$user->onTrial('default');242243// Cancelled but still active?244$user->subscription('default')->onGracePeriod();245```246247### Create Subscription248249```php250// Simple subscription251$user->newSubscription('default', 'price_monthly')252 ->create($paymentMethodId);253254// With trial255$user->newSubscription('default', 'price_monthly')256 ->trialDays(14)257 ->create($paymentMethodId);258```259260### Manage Subscription261262```php263$subscription = $user->subscription('default');264265// Change plan266$subscription->swap('price_yearly');267268// Cancel at period end269$subscription->cancel();270271// Cancel immediately272$subscription->cancelNow();273274// Resume cancelled subscription275$subscription->resume();276```277278### Billing Portal279280```php281// Redirect to customer portal (Stripe)282return $user->redirectToBillingPortal(route('dashboard'));283284// Get portal URL285$url = $user->billingPortalUrl(route('dashboard'));286```287288---289290## Best Practices291292### DO293- Use webhooks for payment confirmation294- Implement grace periods for cancelled subscriptions295- Set up webhook signature verification296- Handle `IncompletePayment` exceptions297- Test with Stripe CLI locally298- Prune old data regularly299300### DON'T301- Trust client-side payment confirmations302- Store card numbers (PCI compliance)303- Skip webhook verification304- Ignore failed payment webhooks305- Forget to handle 3D Secure306- Hardcode prices (use env or config)307308---309310## Laravel 13 Notes311312Cashier Stripe 16.x et Cashier Paddle 2.x sont **compatibles Laravel 13**. Points d'attention :313314- Webhooks : la nouvelle protection CSRF [[laravel-auth]] `PreventRequestForgery` doit exclure les routes webhook (`stripe/webhook`, `paddle/webhook`) via `validateOrigin(except: [...])`315- `serializable_classes` : whitelister les DTOs Cashier si vous serialize des subscriptions (queue)316- PHP 8.3 minimum : Cashier 16.x supporte 8.3+ uniquement317318```php319// bootstrap/app.php320->withMiddleware(function (Middleware $middleware) {321 $middleware->validateOrigin(except: [322 'stripe/*', 'paddle/*',323 ]);324})325```