laravel-billing
Use when implementing subscriptions, invoices, payment methods, webhooks, or billing portals with Laravel Cashier (Stripe or Paddle).
How do I install this agent skill?
npx skills add https://github.com/fusengine/claude-plugins --skill laravel-billingIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a comprehensive library of templates for implementing Stripe and Paddle billing in Laravel applications using Cashier. It follows security best practices such as webhook signature verification and signed route generation. The skill defines a surface for processing external payment provider data, which is a standard requirement for billing functionality.
- Socketwarn
3 alerts: gptSecurity, gptAnomaly
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
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
- Billing code in
/FuseCore/Billing/module - Billable trait on User model in
/FuseCore/User/ - Webhook routes in
/FuseCore/Billing/Routes/web.php - Exclude webhook from CSRF via
preventRequestForgery(except: [...])(L13PreventRequestForgery) - Declare
"User"dependency inmodule.json
→ 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
IncompletePaymentexceptions - 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 (current 16.9) and Cashier Paddle 2.x (current 2.8) are Laravel 13 compatible. Points to watch:
- Webhooks: the new [[laravel-auth]]
PreventRequestForgeryCSRF protection must exclude webhook routes (stripe/webhook,paddle/webhook) viapreventRequestForgery(except: [...]) cache.serializable_classes(defaultfalsein L13): list the classes explicitly if you cache Cashier objects- PHP: Cashier accepts PHP 8.1+, but Laravel 13 requires PHP 8.3 minimum
// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
$middleware->preventRequestForgery(except: [
'stripe/*', 'paddle/*',
]);
})
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/fusengine/claude-plugins/laravel-billing">View laravel-billing on skillZs</a>