/laravel-billing

name: laravel-billing
description: Use when implementing subscriptions, invoices, payment methods, webhooks, or billing portals with Laravel Cashier (Stripe or Paddle).
versions:
  laravel: "13.0"
  cashier-stripe: "16.x"
  cashier-paddle: "2.x"
  php: "8.3"
user-invocable: true
references: 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.md
related-skills: laravel-auth, laravel-api, fusecore

<objective> Covers Laravel Cashier for Stripe and Paddle: choosing between the two (payment processor vs merchant-of-record, tax handling, fees), subscription lifecycle (create, swap, cancel, resume, trials, grace periods), webhooks and signature verification, invoices, payment methods, checkout/customer portal, metered/usage-based billing, team/per-seat billing, dunning (failed-payment recovery), and Pennant-based feature flags per plan. Includes FuseCore modular-project integration. For multi-vendor/marketplace split payments, see laravel-stripe-connect instead. </objective>

Laravel Billing (Cashier)

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:

1. **fuse-ai-pilot:explore-codebase** - Check existing billing setup, User model 2. **fuse-ai-pilot:research-expert** - Verify latest Cashier docs via Context7 3. **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

1. **Use webhooks** - Never rely on client-side confirmations 2. **Handle grace periods** - Allow access until subscription ends 3. **Never store card details** - Use payment tokens/methods 4. **Test with test keys** - Always before production 5. **Verify webhook signatures** - Prevent spoofing attacks 6. **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 in `VerifyCsrfToken`
• [ ] Declare `"User"` dependency in `module.json`

→ See [fusecore skill](../fusecore/SKILL.md) 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?