laravel-cashier-stripe

What this skill does

# Laravel Cashier (Stripe) Skill

Comprehensive assistance with Laravel Cashier (Stripe) development for subscription billing, payment processing, and Stripe integration in Laravel applications.

## When to Use This Skill

This skill should be triggered when:
- Implementing subscription billing in Laravel applications
- Setting up recurring payments with Stripe
- Managing customer subscriptions, trials, and plan changes
- Processing one-time charges or invoices
- Handling Stripe webhooks and events
- Implementing checkout flows with Stripe Checkout
- Managing customer payment methods and cards
- Working with Stripe invoices and billing portals
- Setting up trial periods and proration logic
- Debugging Stripe integration issues in Laravel

## Quick Reference

### Installation and Setup

```bash
# Install Cashier
composer require laravel/cashier

# Publish migrations and migrate
php artisan vendor:publish --tag="cashier-migrations"
php artisan migrate

# Publish config (optional)
php artisan vendor:publish --tag="cashier-config"
```

### Configure Billable Model

```php
use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}
```

### Creating a Subscription

```php
// Basic subscription with trial and checkout
$user->newSubscription('default', 'price_monthly')
    ->trialDays(5)
    ->allowPromotionCodes()
    ->checkout([
        'success_url' => route('checkout.success'),
        'cancel_url' => route('checkout.cancel'),
    ]);
```

### Checking Subscription Status

```php
// Check if user has active subscription
if ($user->subscribed('default')) {
    // User is subscribed to "default" plan
}

// Check specific product subscription
if ($user->subscribedToProduct('prod_premium', 'default')) {
    // User is subscribed to premium product
}

// Check trial status
if ($user->subscription('default')->onTrial()) {
    // User is still in trial period
}
```

### Managing Payment Methods

```php
// Store payment method (in view with Stripe.js)
$intent = $user->createSetupIntent();

// Retrieve payment methods
$paymentMethods = $user->paymentMethods();
$defaultMethod = $user->defaultPaymentMethod();

// Add and update payment methods
$user->addPaymentMethod($paymentMethodId);
$user->updateDefaultPaymentMethod($paymentMethodId);
```

### Swapping Subscription Plans

```php
// Swap to different price/plan
$user->subscription('default')->swap('price_yearly');

// Swap and skip trial
$user->subscription('default')->skipTrial()->swap('price_yearly');
```

### Single Charges and Invoices

```php
// One-time charge
$user->charge(1000, $paymentMethodId, [
    'description' => 'One-time charge',
]);

// Create invoice for service
$user->invoiceFor('Premium Support', 5000, [
    'description' => '3 months of premium support',
]);

// Refund a charge
$user->refund($chargeId);
```

### Canceling Subscriptions

```php
// Cancel immediately
$user->subscription('default')->cancel();

// Cancel at end of billing period
$user->subscription('default')->cancelAtEndOfBillingPeriod();

// Resume canceled subscription
if ($user->subscription('default')->onGracePeriod()) {
    $user->subscription('default')->resume();
}
```

### Working with Invoices

```php
// Get all invoices
$invoices = $user->invoices();

// Get upcoming invoice
$upcomingInvoice = $user->upcomingInvoice('default');

// Download invoice PDF
return $user->invoices()->first()->download();
```

### Billing Portal Integration

```php
// Redirect to Stripe billing portal
Route::get('/billing', function (Request $request) {
    return $request->user()
        ->redirectToBillingPortal(route('dashboard'));
})->middleware(['auth']);
```

### Customer Management

```php
// Create/get Stripe customer
$stripeCustomer = $user->createOrGetStripeCustomer();

// Update customer details
$user->updateStripeCustomer([
    'name' => 'Updated Name',
    'email' => '[email protected]',
]);

// Manage tax IDs
$taxId = $user->createTaxId('eu_vat', 'BE0123456789');
$user->deleteTaxId('txi_belgium');
```

## Key Concepts

### Billable Model
The `Billable` trait adds subscription and payment functionality to your Eloquent models (typically `User`). It provides methods for creating subscriptions, processing charges, managing payment methods, and accessing invoices.

### Subscriptions
Cashier manages recurring billing through subscriptions. Each subscription has:
- **Name**: Identifier like "default" or "premium"
- **Price ID**: Stripe price identifier (e.g., "price_monthly")
- **Status**: Active, trialing, canceled, incomplete, etc.
- **Trial period**: Optional trial days before charging
- **Metered billing**: Support for usage-based pricing

### Payment Methods
Stripe payment methods represent stored payment credentials (cards, bank accounts). Cashier provides helpers to:
- Store payment methods securely via Setup Intents
- Set default payment methods for subscriptions
- Update and delete payment methods
- Handle payment method verification

### Webhooks
Stripe sends webhook events for subscription changes, payment failures, invoice updates, etc. Cashier automatically handles common webhooks, but you can extend functionality by listening to specific events.

### Checkout Sessions
Stripe Checkout provides a pre-built payment page. Cashier simplifies creating checkout sessions for subscriptions and one-time products, handling the complete payment flow with minimal code.

### Invoices
Cashier provides access to Stripe invoices for both subscriptions and one-time charges. You can retrieve, preview, and download invoices as PDFs.

## Reference Files

This skill includes comprehensive documentation in `references/`:

- **other.md** - Complete Laravel Cashier documentation covering:
  - Installation and configuration
  - Subscription management (create, swap, cancel, resume)
  - Payment method handling and Setup Intents
  - Single charges and invoicing
  - Stripe Checkout integration
  - Webhook handling and event processing
  - Customer portal integration
  - Tax ID management
  - Testing strategies

Use `view` to read the reference file when you need detailed information about specific features.

## Working with This Skill

### For Beginners

Start by:
1. Installing Cashier and running migrations
2. Adding the `Billable` trait to your `User` model
3. Setting up environment variables (STRIPE_KEY, STRIPE_SECRET)
4. Creating your first subscription with `newSubscription()`
5. Testing with Stripe test mode API keys

**Basic workflow:**
```php
// 1. Configure model
use Laravel\Cashier\Billable;
class User extends Authenticatable { use Billable; }

// 2. Create subscription
$user->newSubscription('default', 'price_monthly')->create();

// 3. Check status
if ($user->subscribed('default')) {
    // Grant access
}
```

### For Intermediate Users

Focus on:
- Implementing complete checkout flows with Stripe Checkout
- Managing payment method changes and updates
- Handling subscription plan swaps and prorations
- Working with trial periods and grace periods
- Processing one-time charges alongside subscriptions
- Customizing invoice details and tax information

### For Advanced Users

Explore:
- Webhook event customization and extended handling
- Metered billing and usage-based pricing
- Multi-plan subscriptions (multiple subscriptions per user)
- Customer balance and credit management
- Tax ID validation and compliance
- Advanced invoice customization
- Stripe Connect integration for marketplaces
- Testing strategies for subscription flows

### Navigation Tips

- Start with the Quick Reference section for common tasks
- Check Key Concepts to understand core Cashier terminology
- Use `references/other.md` for complete implementation details
- Reference the official Laravel Cashier docs at https://laravel.com/docs/12.x/billing for the latest updates

## Environment Configuration

Required environment variables in `.env`:

```env
STRIPE_KEY=pk_test_your_stripe_publishable_key
STRIPE_SECRET=sk_test_your_stripe_secret_k