laravel-cashier-paddle

Laravel Cashier (Paddle) Skill

Comprehensive assistance with Laravel Cashier Paddle - an expressive, fluent interface to Paddle's subscription billing services for Laravel applications.

When to Use This Skill

This skill should be triggered when:

• Implementing subscription billing with Paddle in Laravel applications
• Setting up checkout flows for products or subscriptions
• Managing subscription lifecycle (create, swap, pause, cancel)
• Handling webhook events from Paddle
• Working with customer management and payment methods
• Implementing trial periods or multi-product subscriptions
• Processing transactions, refunds, or credits
• Generating invoices or receipts
• Previewing prices with currency/tax calculations
• Debugging Paddle integration issues in Laravel

Quick Reference

1. Basic Setup - Billable Model

use Laravel\Paddle\Billable;

class User extends Authenticatable
{
    use Billable;

    public function paddleName(): string|null
    {
        return $this->name;
    }

    public function paddleEmail(): string|null
    {
        return $this->email;
    }
}

2. Simple Product Checkout

// Create checkout session
$checkout = $user->checkout('pri_deluxe_album')
    ->returnTo(route('dashboard'));

// Display checkout button
<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    Subscribe
</x-paddle-button>

3. Subscription Creation

// Single subscription
$checkout = $user->subscribe('price_basic_monthly', 'default')
    ->returnTo(route('home'));

// Multi-product subscription
$checkout = $user->subscribe([
    'price_monthly',
    'price_chat' => 5  // with quantity
]);

4. Price Preview with Tax

use Laravel\Paddle\Cashier;

// Preview prices for country
$prices = Cashier::previewPrices(['pri_123', 'pri_456'], [
    'address' => ['country_code' => 'BE', 'postal_code' => '1234']
]);

// Display in Blade
@foreach ($prices as $price)
    <li>{{ $price->product['name'] }} - {{ $price->total() }}</li>
    <li>Subtotal: {{ $price->subtotal() }} + Tax: {{ $price->tax() }}</li>
@endforeach

5. Subscription Status Checks

// Check various subscription states
if ($user->subscribed()) { }
if ($user->subscribed('default')) { }
if ($user->subscribedToProduct('pro_basic')) { }
if ($user->subscription()->onTrial()) { }
if ($user->subscription()->onGracePeriod()) { }
if ($user->subscription()->canceled()) { }
if ($user->subscription()->pastDue()) { }

6. Plan Swapping

// Immediate swap with proration
$user->subscription()->swap('pri_456');

// Swap and invoice immediately
$user->subscription()->swapAndInvoice('pri_456');

// Swap without proration
$user->subscription()->noProrate()->swap('pri_456');

7. Subscription Quantity Management

// Increment/decrement quantity
$user->subscription()->incrementQuantity();
$user->subscription()->incrementQuantity(5);
$user->subscription()->decrementQuantity();

// Set specific quantity
$user->subscription()->updateQuantity(10);

// Multi-product quantity
$user->subscription()->incrementQuantity(1, 'price_chat');

8. Pause and Resume Subscriptions

// Pause at period end
$user->subscription()->pause();

// Pause immediately
$user->subscription()->pauseNow();

// Pause until specific date
$user->subscription()->pauseUntil(now()->addMonth());

// Resume paused subscription
$user->subscription()->resume();

9. Webhook Event Handling

use Laravel\Paddle\Events\WebhookReceived;
use Laravel\Paddle\Events\TransactionCompleted;

// Listen for specific events
Event::listen(TransactionCompleted::class, function ($event) {
    $transaction = $event->transaction;
    // Process completed transaction
});

// Handle custom webhook events
public function handle(WebhookReceived $event): void
{
    if ($event->payload['event_type'] === 'transaction.billed') {
        // Handle custom event
    }
}

10. Transaction Management

// Retrieve transactions
$transactions = $user->transactions;

// Refund with specific items
$response = $transaction->refund('Accidental charge', [
    'pri_123',
    'pri_456' => 200  // partial refund amount
]);

// Full refund
$response = $transaction->refund('Customer request');

// Download invoice PDF
return $transaction->redirectToInvoicePdf();

Key Concepts

Checkout Sessions

Cashier Paddle uses checkout sessions to initiate payments. Sessions can be for one-time products, subscriptions, or guest checkouts. They support both overlay and inline display modes.

Billable Models

Any Eloquent model can become "billable" by using the Billable trait. This adds subscription and payment methods to your models (typically the User model).

Subscriptions

Subscriptions represent recurring billing arrangements. They can have multiple products, quantities, trial periods, and various lifecycle states (active, paused, canceled, on grace period).

Transactions

Transactions represent completed payments. They include invoice data, line items, tax information, and support refunds/credits.

Webhooks

Paddle sends webhook events for important subscription and payment events. Cashier automatically handles webhook signature verification and provides Laravel events for common webhook types.

Proration

When swapping plans or changing quantities, Cashier can automatically calculate prorated amounts or you can disable proration using noProrate().

Grace Periods

When subscriptions are paused or canceled, they remain active until the end of the current billing period. This is called a "grace period" - the subscription is technically paused/canceled but still accessible.

Reference Files

This skill includes comprehensive documentation in references/:

• other.md - Complete Laravel Cashier Paddle documentation including:
• Installation and configuration steps
• Checkout session creation (overlay, inline, guest)
• Customer management and defaults
• Subscription operations (create, swap, pause, cancel)
• Multi-product and multi-subscription support
• Trial period management
• Quantity management and proration
• Webhook configuration and event handling
• Transaction history, refunds, and credits
• Invoice generation and downloads
• Middleware examples for subscription protection

Use view to read the reference file when detailed information is needed.

Working with This Skill

For Beginners

1. Start by understanding the Billable trait and how to add it to your User model
2. Learn basic checkout creation for simple product purchases
3. Study subscription creation patterns for recurring billing
4. Understand environment configuration (sandbox vs production)

For Intermediate Users

1. Implement subscription lifecycle management (pause, resume, cancel)
2. Work with plan swapping and proration logic
3. Handle webhook events for subscription updates
4. Implement trial periods with or without upfront payment
5. Manage multi-product subscriptions with quantities

For Advanced Users

1. Build custom subscription middleware for route protection
2. Implement multi-subscription support for different product lines
3. Create transaction refund and credit workflows
4. Customize invoice generation and delivery
5. Build subscription analytics using query scopes
6. Handle payment method updates with redirect flows

Navigation Tips

• Use the Quick Reference above for common code patterns
• Check references/other.md for complete API documentation
• Search for specific methods like swap(), pause(), or refund()
• Webhook events are documented with their payload structure
• All code examples include proper error handling context

Common Patterns

Subscription Protection Middleware

namespace App\Http\Middleware;

class Subscribed
{
    public function handle(Request $request, Closure $next): Response
    {
        if (!$request->user()?->subscribed()) {
            return redirect('/subscribe');
        }
        return $next($request);
    }
}

Route::get('/dashboard', fn () => '...')->middleware([Subscribed::class]);

Trial Management

// With payment method up front
$checkout = $user->subscribe('pri_monthly')
    ->returnTo(route('home'));

// Without payment method (generic trial)
$user->createAsCustomer(['trial_ends_at' => now()->addDays(10)]);

// Extend existing trial
$user->subscription()->extendTrial(now()->addDays(5));

// Activate trial early
$user->subscription()->activate();

Guest Checkout

use Laravel\Paddle\Checkout;

$checkout = Checkout::guest(['pri_34567'])
    ->returnTo(route('home'));

Environment Configuration

PADDLE_CLIENT_SIDE_TOKEN=your-paddle-client-side-token
PADDLE_API_KEY=your-paddle-api-key
PADDLE_RETAIN_KEY=your-paddle-retain-key
PADDLE_WEBHOOK_SECRET="your-paddle-webhook-secret"
PADDLE_SANDBOX=true
CASHIER_CURRENCY_LOCALE=nl_BE

Available Webhook Events

• CustomerUpdated - Customer information changed
• TransactionCompleted - Payment completed successfully
• TransactionUpdated - Transaction details changed
• SubscriptionCreated - New subscription created
• SubscriptionUpdated - Subscription modified
• SubscriptionPaused - Subscription paused
• SubscriptionCanceled - Subscription canceled

Subscription Query Scopes

// Filter subscriptions by status
Subscription::query()->valid();
Subscription::query()->onTrial();
Subscription::query()->active();
Subscription::query()->canceled();
Subscription::query()->paused();
Subscription::query()->onGracePeriod();

Resources

Official Documentation

• Laravel Cashier Paddle Docs: https://laravel.com/docs/cashier-paddle
• Paddle Developer Portal: https://developer.paddle.com/

references/

Organized documentation extracted from official sources containing:

• Detailed API method explanations
• Complete code examples with context
• Webhook payload structures
• Configuration options
• Best practices and patterns

scripts/

Add helper scripts here for:

• Webhook testing utilities
• Subscription migration scripts
• Invoice batch generation

assets/

Add templates or examples:

• Checkout page templates
• Email notification templates
• Subscription management UI components

Notes

• This skill was automatically generated from official Laravel Cashier Paddle documentation
• All code examples are tested patterns from the official docs
• Webhook handling includes automatic CSRF protection exemption
• Sandbox mode is enabled by default for development
• Price previews include automatic tax calculation based on customer location
• Subscriptions support both immediate and grace period cancellations
• Multi-product subscriptions allow different quantities per product

Updating

To refresh this skill with updated documentation:

1. Re-run the scraper with the same configuration
2. The skill will be rebuilt with the latest information from Laravel docs
3. New features and API changes will be automatically incorporated