Laravel Cashier Paddle

https://github.com/laravel/cashier-paddle
Admin
Laravel Cashier Paddle is a PHP library that integrates Laravel with Paddle's subscription billing,...
Tokens:46,900
Snippets:725
Trust Score:9.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Array Type Examples

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/types.md

Examples of array structures used for normalized items, custom data, and configuration options.

```php
// Normalized items array
[
    ['priceId' => 'price_123', 'quantity' => 1],
    ['priceId' => 'price_456', 'quantity' => 2],
]

// Custom data array
[
    'key1' => 'value1',
    'key2' => 'value2',
]

// Options array
[
    'customer_id' => 'ctm_123',
    'address' => ['country' => 'US'],
]
```

--------------------------------

### Getting Started with Billable Trait and Checkout

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/README.md

Add the Billable trait to your Eloquent model, create a customer, and initiate a subscription checkout.

```php
// 1. Add Billable trait to model
use Laravel\Paddle\Billable;

class User extends Model {
    use Billable;
}

// 2. Create customer (lazy loads if needed)
$customer = $user->createAsCustomer();

// 3. Create subscription checkout
$checkout = $user->subscribe('price_monthly');

// 4. In view - render checkout
<x-paddle-checkout :checkout="$checkout" />
```

--------------------------------

### Iterate Price Previews

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/types.md

Example of retrieving and iterating over a collection of PricePreview instances.

```php
$previews = Cashier::previewPrices('price_123');
foreach ($previews as $preview) {
    // $preview is a PricePreview instance
}
```

--------------------------------

### Preview Prices for Customer

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Example of previewing prices and accessing the total for each preview.

```php
$previews = $user->previewPrices('price_123');
foreach ($previews as $preview) {
    echo $preview->total(); // Formatted with tax for customer's region
}
```

--------------------------------

### Cashier::api() example

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/cashier.md

Perform GET and POST requests to the Paddle API with automatic authentication.

```php
$response = Cashier::api('GET', 'customers', ['status' => 'active']);
$customers = $response['data'];

// POST with payload
$response = Cashier::api('POST', 'customers', [
    'name' => 'John Doe',
    'email' => 'john@example.com',
]);
```

--------------------------------

### Environment Setup: Production

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/configuration.md

Configure environment variables for the live Paddle production environment.

```env
PADDLE_SANDBOX=false
PADDLE_CLIENT_SIDE_TOKEN=your_live_token
PADDLE_API_KEY=your_live_api_key
PADDLE_WEBHOOK_SECRET=your_live_webhook_secret
CASHIER_CURRENCY=USD
```

--------------------------------

### Environment Setup: Sandbox

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/configuration.md

Configure environment variables for the Paddle sandbox environment.

```env
PADDLE_SANDBOX=true
PADDLE_CLIENT_SIDE_TOKEN=your_sandbox_token
PADDLE_API_KEY=your_sandbox_api_key
PADDLE_WEBHOOK_SECRET=your_sandbox_webhook_secret
CASHIER_CURRENCY=USD
CASHIER_CURRENCY_LOCALE=en
```

--------------------------------

### subscription() Usage Example

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Retrieving a subscription by type, defaulting to 'default'.

```php
$sub = $user->subscription('premium');
$default = $user->subscription(); // Gets 'default' type
```

--------------------------------

### previewPrices() Method Signature

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

The method signature for getting price previews for a customer.

```php
public function previewPrices($items, array $options = []): \Illuminate\Support\Collection
```

--------------------------------

### Cashier::previewPrices() example

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/cashier.md

Preview prices for specific items and iterate through the resulting collection to display totals.

```php
$previews = Cashier::previewPrices(['price_id_123' => 1, 'price_id_456' => 2]);
foreach ($previews as $preview) {
    echo $preview->total(); // "£29.99"
}
```

--------------------------------

### subscriptions() Usage Example

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Retrieving all subscriptions or filtering for active ones.

```php
$subs = $user->subscriptions; // All subscriptions
$activeSubs = $user->subscriptions()->active()->get();
```

--------------------------------

### SubscriptionItem Usage

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/supporting-classes.md

Examples for retrieving subscription items, finding a specific item, and updating quantities.

```php
// Get subscription items
$items = $subscription->items;

// Check specific item
$item = $subscription->findItemOrFail('price_123');

// Update quantity (use subscription methods instead)
$subscription->updateQuantity(5, $item);
```

--------------------------------

### onTrial() Usage Example

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Checking trial status for the default or a specific subscription type and price.

```php
if ($user->onTrial()) {
    echo "Customer is on trial";
}

if ($user->onTrial('premium', 'price_123')) {
    echo "Premium subscription has trial for this price";
}
```

--------------------------------

### Create a Paddle Customer

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Example of creating a customer with specific options including name, email, and trial end date.

```php
$customer = $user->createAsCustomer([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'trial_ends_at' => now()->addDays(14),
]);
```

--------------------------------

### ModelNotFoundException Handling

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/errors.md

Example of catching a ModelNotFoundException when a subscription item cannot be found.

```php
try {
    $subscription->findItemOrFail('invalid_price_id');
} catch (ModelNotFoundException $e) {
    echo "Price not found in subscription";
}
```

--------------------------------

### Access Customer Relationship

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Example of accessing the customer relationship and performing eager loading.

```php
$customer = $user->customer;
if ($customer) {
    echo $customer->paddle_id;
}

// Eager load
$users = User::with('customer')->get();
```

--------------------------------

### Swap subscription with immediate proration

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/subscription.md

Example of using the prorateImmediately method when swapping a subscription to a new price ID.

```php
$subscription->prorateImmediately()->swap('new_price_id');
```

--------------------------------

### Querying customers

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/customer.md

Examples of querying the customers table for specific statuses or identifiers.

```php
// Get all customers
$customers = Customer::all();

// Get customers on trial
$onTrial = Customer::whereNotNull('trial_ends_at')
    ->where('trial_ends_at', '>', now())
    ->get();

// Get customers with expired trial
$expired = Customer::whereNotNull('trial_ends_at')
    ->where('trial_ends_at', '<=', now())
    ->get();

// Get customer by Paddle ID
$customer = Customer::where('paddle_id', 'ctm_123')->first();

// Get customer for a specific user
$customer = $user->customer;
```

--------------------------------

### Manage Generic Trials

Source: https://github.com/laravel/cashier-paddle/blob/2.x/resources/boost/skills/cashier-paddle-development/references/subscriptions.md

Create customers with trials that do not require upfront payment. Use `onTrial()` and `onGenericTrial()` to check trial status, and `trialEndsAt()` to get the trial end date. Extend or activate trials as needed.

```php
$user->createAsCustomer(['trial_ends_at' => now()->addDays(14)]);

$user->onTrial();         // true
$user->onGenericTrial();  // true
$user->trialEndsAt();     // Carbon instance
```

```php
$user->subscription()->extendTrial(now()->addDays(7));
$user->subscription()->activate(); // end trial immediately, begin billing
```

--------------------------------

### Cashier::webhookUrl() example

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/cashier.md

Retrieve the configured URL for receiving Paddle webhook events.

```php
$url = Cashier::webhookUrl();
// Returns: https://myapp.com/paddle/webhook (or custom config value)
```

--------------------------------

### Cashier::apiUrl() example

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/cashier.md

Retrieve the base URL for the Paddle API, which varies based on the environment configuration.

```php
$url = Cashier::apiUrl();
// Returns: https://api.paddle.com or https://sandbox-api.paddle.com
```

--------------------------------

### checkout(string|array $prices, int $quantity)

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Get a checkout instance for given prices.

```APIDOC
## checkout(string|array $prices, int $quantity = 1)

### Description
Get a checkout instance for given prices. Automatically creates customer if needed.

### Parameters
- **$prices** (string|array) - Required - Single price ID or array of price => quantity
- **$quantity** (int) - Optional - Quantity for single price

### Returns
- **Checkout** - Checkout instance
```

--------------------------------

### Listen for CustomerUpdated event

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/events.md

Example listener for the CustomerUpdated event, which is dispatched when customer details are updated on Paddle.

```php
Event::listen(CustomerUpdated::class, function ($event) {
    $customer = $event->customer;
    
    // Sync email back to user model
    $event->billable->update(['email' => $customer->email]);
});
```

--------------------------------

### Listen for TransactionCompleted event

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/events.md

Example listener for the TransactionCompleted event, which is dispatched when a payment is received.

```php
Event::listen(TransactionCompleted::class, function ($event) {
    $transaction = $event->transaction;
    
    // Record in accounting system
    AccountingService::recordPayment(
        $transaction->paddle_id,
        $transaction->total,
        $transaction->currency
    );
    
    // Send receipt
    Mail::send(new PaymentReceived($event->billable, $transaction));
});
```

--------------------------------

### Cashier::findBillable() example

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/cashier.md

Retrieve a billable model instance using a Paddle customer ID.

```php
$user = Cashier::findBillable('ctm_123456');
if ($user) {
    echo $user->name; // The billable model
}
```

--------------------------------

### Handling API Errors in Application Logic

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/errors.md

Example of handling specific API errors during customer creation.

```php
use Laravel\Paddle\Exceptions\PaddleException;

try {
    $user->createAsCustomer(['email' => 'test@example.com']);
} catch (PaddleException $e) {
    if (str_contains($e->getMessage(), 'already exists')) {
        // Customer already created
        return $user->customer;
    }
    
    // Log error for support
    Log::error('Customer creation failed', [
        'user_id' => $user->id,
        'error' => $e->getError(),
    ]);
    
    // Show user-friendly message
    throw new \Exception('Unable to create account. Please try again later.');
}
```

--------------------------------

### Listen for TransactionUpdated event

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/events.md

Example listener for the TransactionUpdated event, which is dispatched when a transaction status changes.

```php
Event::listen(TransactionUpdated::class, function ($event) {
    $transaction = $event->transaction;
    
    if ($transaction->status === 'completed') {
        // Process completion
    } elseif ($transaction->status === 'past_due') {
        // Handle overdue payment
        NotifyOverduePayment::dispatch($event->billable);
    }
});
```

--------------------------------

### Configure and Check Trial Periods

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/README.md

Create customers with trial periods and check trial status or end dates.

```php
// Generic trial (customer-level)
$user->createAsCustomer(['trial_ends_at' => now()->addDays(14)]);

// Subscription trial (price-level in Paddle)
// Set via Paddle dashboard on price

// Check trial
if ($user->onTrial()) { /* ... */ }
$user->trialEndsAt(); // Get end date
```

--------------------------------

### currency()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/transaction.md

Get the currency object for this transaction.

```APIDOC
## currency()

### Description
Get the currency object for this transaction.

### Returns
- **Money\Currency** - Money\Currency instance
```

--------------------------------

### Get subscription data with asPaddleSubscription()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/subscription.md

Fetches complete subscription data from the Paddle API. Optionally accepts an include parameter to fetch related data like 'next_transaction'.

```php
public function asPaddleSubscription(string|null $include = null): array
```

```php
$data = $subscription->asPaddleSubscription();
$withNext = $subscription->asPaddleSubscription('next_transaction');
```

--------------------------------

### transactions()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Get all transactions for this billable model.

```APIDOC
## transactions()

### Description
Get all transactions for this billable model (MorphMany relation, ordered by billing date).

### Returns
- **MorphMany** - MorphMany relationship query
```

--------------------------------

### Run Migrations

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/configuration.md

Command to execute the published migrations and create the necessary database tables.

```bash
php artisan migrate
```

--------------------------------

### Initialize Money Currency

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/types.md

Demonstrates creating a new Currency instance using the moneyphp/money library.

```php
use Money\Currency;

$currency = new Currency('USD');
$code = $currency->getCode(); // 'USD'
```

--------------------------------

### invoicePdf()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/transaction.md

Get the URL to download the invoice PDF.

```APIDOC
## invoicePdf()

### Description
Get the URL to download the invoice PDF. Only available for transactions with invoice numbers.

### Returns
- **string|null** - Full PDF download URL or null if no invoice
```

--------------------------------

### Initialize CashierFake with Static Factory

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/supporting-classes.md

Use the static fake method to initialize the Cashier testing utility with predefined customer and subscription data.

```php
Cashier::fake([
    'customers' => ['id' => 'ctm_123'],
    'subscriptions' => ['id' => 'sub_123'],
]);
```

--------------------------------

### tax()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/transaction.md

Get the tax amount formatted as currency.

```APIDOC
## tax()

### Description
Get the tax amount formatted as currency.

### Returns
- **string** - Formatted currency string
```

--------------------------------

### total()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/transaction.md

Get the total transaction amount formatted as currency.

```APIDOC
## total()

### Description
Get the total transaction amount formatted as currency.

### Returns
- **string** - Formatted currency string (e.g., "$29.99")
```

--------------------------------

### Publish and Run Migrations

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/README.md

Commands to publish the Cashier migration files and apply them to the database.

```bash
php artisan vendor:publish --tag=cashier-migrations
php artisan migrate
```

--------------------------------

### Get currency object with currency()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/transaction.md

Retrieve the Money\Currency instance for the transaction.

```php
$curr = $transaction->currency();
echo $curr->getCode(); // "USD"
```

--------------------------------

### activate()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/subscription.md

Ends the trial period immediately and activates the subscription.

```APIDOC
## activate()

### Description
Forces the trial to end immediately and activates the subscription. The subscription becomes active and billing starts immediately.

### Returns
- **$this** - Returns the subscription instance for method chaining.
```

--------------------------------

### Accessing Transaction Subscription

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/transaction.md

Example of checking the status of a subscription associated with a transaction.

```php
if ($transaction->subscription) {
    echo $transaction->subscription->status;
}
```

--------------------------------

### activate() usage

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/subscription.md

Forces the trial to end immediately and activates the subscription, triggering immediate billing.

```php
if ($customer->confirmsEmail()) {
    $subscription->activate();
}
```

--------------------------------

### Resume Subscription with resume()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/subscription.md

Resumes a paused subscription immediately or at a specified future date. Throws a LogicException if the subscription is not currently paused.

```php
$subscription->resume(); // Resume immediately
$subscription->resume(now()->addDays(7)); // Resume in 7 days
```

--------------------------------

### checkout() Method and Usage

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Generates a checkout instance for specified prices, automatically creating a customer if necessary.

```php
public function checkout(string|array $prices, int $quantity = 1): \Laravel\Paddle\Checkout
```

```php
$checkout = $user->checkout('price_monthly');
$checkout = $user->checkout(['price_1' => 1, 'price_2' => 2]);

// Use in view
return view('checkout', ['checkout' => $checkout]);
```

--------------------------------

### chargeAndInvoice()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/subscription.md

Adds charges and bills the subscription immediately.

```php
public function chargeAndInvoice(string|array $items): $this
```

```php
$subscription->chargeAndInvoice('price_addon_123');
```

--------------------------------

### Mocking a Subscription Created Webhook

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/webhooks.md

Demonstrates how to simulate a subscription.created webhook event in a test case using postJson and asserting that the corresponding event is dispatched.

```php
use Laravel\Paddle\Events\SubscriptionCreated;

public function test_subscription_created_webhook()
{
    Event::fake();
    
    $payload = [
        'event_type' => 'subscription.created',
        'data' => [
            'id' => 'sub_123',
            'customer_id' => 'ctm_123',
            'status' => 'active',
            'items' => [
                [
                    'price' => [
                        'id' => 'price_123',
                        'product_id' => 'prod_123',
                    ],
                    'status' => 'active',
                    'quantity' => 1,
                ]
            ],
            'custom_data' => ['subscription_type' => 'premium'],
        ]
    ];
    
    $response = $this->postJson('/paddle/webhook', $payload);
    
    $response->assertOk();
    Event::assertDispatched(SubscriptionCreated::class);
}
```

--------------------------------

### Accessing Transaction Billable Model

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/transaction.md

Example of accessing the billable model associated with a transaction.

```php
$user = $transaction->billable;
```

--------------------------------

### subscribedToPrice() Usage Example

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Checking if the user is subscribed to one of the provided price IDs.

```php
if ($user->subscribedToPrice(['price_monthly', 'price_yearly'])) {
    // Subscribed to monthly or yearly plan
}
```

--------------------------------

### subscribedToProduct() Usage Example

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Checking if the user is subscribed to one of the provided product IDs.

```php
if ($user->subscribedToProduct(['prod_gold', 'prod_platinum'])) {
    // Subscribed to either premium product
}
```

--------------------------------

### subscribed() Usage Example

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Checking for active subscriptions, optionally filtered by type and price.

```php
if ($user->subscribed()) {
    // Show premium content
}

if ($user->subscribed('premium', 'price_monthly')) {
    // Premium monthly subscriber
}
```

--------------------------------

### trialEndsAt() Usage Example

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Checking if a trial has expired using the trial end date.

```php
$endsAt = $user->trialEndsAt('premium');
if ($endsAt && $endsAt->isPast()) {
    echo "Trial expired";
}
```

--------------------------------

### Optional Environment Variables

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/README.md

Additional configuration variables for sandbox mode, client-side tokens, and currency settings.

```env
PADDLE_SANDBOX=false
PADDLE_CLIENT_SIDE_TOKEN=your_token
CASHIER_CURRENCY=USD
CASHIER_CURRENCY_LOCALE=en
CASHIER_PATH=paddle
```

--------------------------------

### Override paddleEmail()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Example of overriding the default paddleEmail method to customize the customer email.

```php
public function paddleEmail()
{
    return $this->contact_email ?? $this->email;
}
```

--------------------------------

### Override paddleName()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Example of overriding the default paddleName method to customize the customer name.

```php
public function paddleName()
{
    return "{$this->first_name} {$this->last_name}";
}
```

--------------------------------

### options()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/checkout.md

Converts the checkout object into an array of options compatible with the Paddle.Checkout.open() JavaScript method.

```APIDOC
## options()

### Description
Convert checkout to an array of options compatible with Paddle.Checkout.open() JavaScript method.

### Signature
`public function options(): array`

### Returns
Options array with settings, items, customer, and customData.
```

--------------------------------

### Configuring Cashier Paddle

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/README.md

Set environment variables and perform programmatic configuration for models and formatting.

```php
// Environment variables
PADDLE_API_KEY=...
PADDLE_WEBHOOK_SECRET=...
PADDLE_CLIENT_SIDE_TOKEN=...
CASHIER_CURRENCY=USD
PADDLE_SANDBOX=false

// Programmatic configuration
Cashier::useCustomerModel(CustomCustomer::class);
Cashier::keepPastDueSubscriptionsActive();
Cashier::formatCurrencyUsing(function(...) { ... });
```

--------------------------------

### Format tax amount with tax()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/transaction.md

Get the tax amount formatted as a currency string.

```php
echo "Tax: " . $transaction->tax();
```

--------------------------------

### Redirect to invoice PDF with redirectToInvoicePdf()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/transaction.md

Redirect the user to the invoice PDF download. Throws a LogicException if no invoice is available.

```php
return $transaction->redirectToInvoicePdf();
```

--------------------------------

### Handling LogicException with updateQuantity

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/errors.md

Demonstrates catching a LogicException when attempting to update a subscription quantity to zero.

```php
try {
    $subscription->updateQuantity(0); // Invalid
} catch (LogicException $e) {
    echo $e->getMessage(); // "Quantities of zero are not allowed."
}
```

--------------------------------

### Expose Local Development Server for Webhooks

Source: https://github.com/laravel/cashier-paddle/blob/2.x/resources/boost/skills/cashier-paddle-development/references/webhooks.md

Use a reverse proxy tool like `expose` or `ngrok` to make your local development server accessible from the internet. This is required to receive webhook notifications from Paddle during local development.

```bash
# Using Expose
expose share http://your-app.test
```

```bash
# Using Ngrok
ngrok http 80
```

--------------------------------

### Checkout::customer Factory Method

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/checkout.md

Creates a checkout instance for an authenticated customer.

```php
public static function customer(Customer $customer, array $items = []): self
```

```php
$checkout = Checkout::customer($user->customer, ['price_pro' => 1]);
```

--------------------------------

### transaction.completed Webhook Data

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/webhooks.md

Example JSON payload for the transaction.completed event, which triggers the handleTransactionCompleted() method.

```json
{
  "event_type": "transaction.completed",
  "data": {
    "id": "txn_12345",
    "customer_id": "ctm_12345",
    "subscription_id": "sub_12345",
    "invoice_number": "INV-001",
    "status": "completed",
    "currency_code": "USD",
    "billed_at": "2024-09-07T12:00:00Z",
    "details": {
      "totals": {
        "total": "2999",
        "tax": "0"
      }
    }
  }
}
```

--------------------------------

### customer.updated Webhook Data

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/webhooks.md

Example JSON payload for the customer.updated event, which triggers the handleCustomerUpdated() method.

```json
{
  "event_type": "customer.updated",
  "data": {
    "id": "ctm_12345",
    "name": "John Doe",
    "email": "john@example.com"
  }
}
```

--------------------------------

### Checkout::guest()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/checkout.md

Creates a checkout instance for a guest user without an existing customer record.

```APIDOC
## Checkout::guest(array $items)

### Description
Create a checkout instance for a guest (no customer record).

### Parameters
- **$items** (array) - Optional - Price IDs and quantities

### Returns
- **Checkout** - New Checkout instance

### Example
```php
$checkout = Checkout::guest(['price_monthly' => 1]);
```
```

--------------------------------

### newSubscription() Method and Usage

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Initializes a subscription builder for custom subscription configurations.

```php
public function newSubscription(int $amount, string $name, string $type = Subscription::DEFAULT_TYPE): \Laravel\Paddle\SubscriptionBuilder
```

```php
$checkout = $user->newSubscription(2999, 'Premium Plan')
    ->monthly()
    ->quantity(5)
    ->checkout();
```

--------------------------------

### Checkout::customer()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/checkout.md

Creates a checkout instance for an authenticated customer.

```APIDOC
## Checkout::customer(Customer $customer, array $items)

### Description
Create a checkout instance for an authenticated customer.

### Parameters
- **$customer** (Customer) - Required - Customer instance
- **$items** (array) - Optional - Price IDs and quantities

### Returns
- **Checkout** - New Checkout instance

### Example
```php
$checkout = Checkout::customer($user->customer, ['price_pro' => 1]);
```
```

--------------------------------

### SubscriptionBuilder daily() Method

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/supporting-classes.md

Sets the billing interval to daily. Returns the instance for method chaining.

```php
public function daily(): $this
```

--------------------------------

### Cashier::apiUrl()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/cashier.md

Get the base URL for the Paddle API based on the current environment configuration.

```APIDOC
## Cashier::apiUrl()

### Description
Get the Paddle API base URL (live or sandbox based on config).

### Returns
API base URL string
```

--------------------------------

### Format total amount with total()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/transaction.md

Get the total transaction amount formatted as a currency string.

```php
echo "Total: " . $transaction->total();
```

--------------------------------

### Publish Migrations

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/configuration.md

Command to publish the Cashier migration files to your application.

```bash
php artisan vendor:publish --tag=cashier-migrations
```

--------------------------------

### Listen to SubscriptionCreated event

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/events.md

Handles the SubscriptionCreated event to perform actions like sending a welcome email and logging the subscription details.

```php
Event::listen(SubscriptionCreated::class, function ($event) {
    $user = $event->billable;
    $subscription = $event->subscription;
    
    // Send welcome email
    Mail::send(new SubscriptionWelcome($user));
    
    // Log subscription
    Log::info('Subscription created', [
        'user_id' => $user->id,
        'subscription_id' => $subscription->paddle_id,
    ]);
});
```

--------------------------------

### Define Polymorphic billable_type values

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/types.md

Examples of models that can be used as billable entities when implementing the Billable trait.

```php
// billable_type values - can be any model:
'App\Models\User'
'App\Models\Account'
'App\Models\Organization'
// ... any model with Billable trait
```

--------------------------------

### createAsCustomer(array $options = [])

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Creates a Paddle customer record for the billable model. It reuses existing customers if the email matches or if a customer is already linked to the model.

```APIDOC
## createAsCustomer(array $options = [])

### Description
Create a Paddle customer record for this billable model. If a customer already exists with the same email, it reuses that. If one already exists linked to this model, it returns it.

### Parameters
- **$options** (array) - Optional - Customer data (name, email, trial_ends_at)

### Returns
- **Customer** (instance) - The created or retrieved Customer instance.

### Example
```php
$customer = $user->createAsCustomer([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'trial_ends_at' => now()->addDays(14),
]);
```
```

--------------------------------

### Project File Organization

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/README.md

The directory structure of the documentation files for the Laravel Cashier Paddle package.

```text
/output/
├── README.md                 # This file
├── cashier-overview.md       # Project overview
├── cashier.md                # Cashier facade
├── billable.md               # Billable trait
├── subscription.md           # Subscription model
├── transaction.md            # Transaction model
├── checkout.md               # Checkout system
├── customer.md               # Customer model
├── supporting-classes.md     # SubscriptionBuilder, Price, etc.
├── events.md                 # Events documentation
├── webhooks.md               # Webhook handling
├── configuration.md          # Configuration reference
├── types.md                  # Types and type definitions
└── errors.md                 # Error handling
```

--------------------------------

### Checkout::guest Factory Method

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/checkout.md

Creates a checkout instance for a guest without a customer record.

```php
public static function guest(array $items = []): self
```

```php
$checkout = Checkout::guest(['price_monthly' => 1]);
```

--------------------------------

### returnTo() Configuration

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/checkout.md

Sets the URL for redirecting the customer after a successful checkout.

```php
$checkout->returnTo(route('billing.success'));
$checkout->returnTo('https://example.com/thank-you');
```

--------------------------------

### createAsCustomer() Method Signature

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

The method signature for creating a Paddle customer record.

```php
public function createAsCustomer(array $options = []): \Laravel\Paddle\Customer
```

--------------------------------

### Mock Cashier in Tests

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/configuration.md

Use CashierFake in your test setup to mock API responses for customers and subscriptions.

```php
public function setUp(): void
{
    parent::setUp();
    
    Cashier::fake([
        'customers' => ['id' => 'ctm_test'],
        'subscriptions' => ['id' => 'sub_test'],
    ]);
}
```

--------------------------------

### Handle Fallback Customer Creation

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/errors.md

Catch LogicException when creating a customer to handle cases where the customer record might already exist.

```php
try {
    $customer = $user->createAsCustomer();
} catch (LogicException $e) {
    // Customer might already exist
    $customer = Customer::where('paddle_id', $paddleId)->first();
    if (!$customer) {
        throw $e;
    }
}
```

--------------------------------

### Register events in EventServiceProvider

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/events.md

Example of mapping various Paddle events to their respective listeners within the Laravel EventServiceProvider.

```php
namespace App\Providers;

use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;
use Laravel\Paddle\Events\{
    SubscriptionCreated,
    SubscriptionUpdated,
    SubscriptionCanceled,
    SubscriptionPaused,
    TransactionCompleted,
    TransactionUpdated,
    CustomerUpdated,
    WebhookReceived,
    WebhookHandled,
};
use App\Listeners\{
    HandleSubscriptionCreated,
    HandleSubscriptionUpdated,
    HandleSubscriptionCanceled,
    HandleSubscriptionPaused,
    HandleTransactionCompleted,
    HandleTransactionUpdated,
    HandleCustomerUpdated,
    LogWebhookReceived,
    LogWebhookHandled,
};

class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        SubscriptionCreated::class => [HandleSubscriptionCreated::class],
        SubscriptionUpdated::class => [HandleSubscriptionUpdated::class],
        SubscriptionCanceled::class => [HandleSubscriptionCanceled::class],
        SubscriptionPaused::class => [HandleSubscriptionPaused::class],
        TransactionCompleted::class => [HandleTransactionCompleted::class],
        TransactionUpdated::class => [HandleTransactionUpdated::class],
        CustomerUpdated::class => [HandleCustomerUpdated::class],
        WebhookReceived::class => [LogWebhookReceived::class],
        WebhookHandled::class => [LogWebhookHandled::class],
    ];
}
```

--------------------------------

### Manage Multi-Tier Subscriptions

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/README.md

Check subscription types and swap between pricing tiers using the subscription instance.

```php
// Check subscription type
if ($user->subscribed('premium', 'price_monthly')) {
    // Show premium features
}

// Change tier
$subscription = $user->subscription('premium');
$subscription->swap('price_premium_yearly');
```

--------------------------------

### Manage subscription types

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/configuration.md

Shows how to subscribe a user to a specific type and retrieve that subscription.

```php
// In model or controller
$user->subscribe('price_id', 'premium'); // Sets type to 'premium'
$user->subscription('premium'); // Retrieves 'premium' type
```

--------------------------------

### Cashier::normalizeItems() example

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/cashier.md

Convert price IDs or associative arrays into the standard format required by Paddle API requests.

```php
// Array with quantities
$normalized = Cashier::normalizeItems(['price_id_1' => 2, 'price_id_2' => 1]);
// Result: [['price_id' => 'price_id_1', 'quantity' => 2], ...]

// Single price string
$normalized = Cashier::normalizeItems('price_id_1');
// Result: [['price_id' => 'price_id_1', 'quantity' => 1]]
```

--------------------------------

### Programmatic Configuration in AppServiceProvider

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/configuration.md

Configure custom models, disable automatic route registration, and define currency formatting logic within the boot method of a service provider.

```php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Laravel\Paddle\Cashier;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        // Use custom customer model
        Cashier::useCustomerModel(App\Models\PaddleCustomer::class);
        
        // Use custom subscription model
        Cashier::useSubscriptionModel(App\Models\PaddleSubscription::class);
        
        // Use custom subscription item model
        Cashier::useSubscriptionItemModel(App\Models\PaddleSubscriptionItem::class);
        
        // Use custom transaction model
        Cashier::useTransactionModel(App\Models\PaddleTransaction::class);
        
        // Don't register routes automatically
        Cashier::ignoreRoutes();
        
        // Keep past-due subscriptions as valid
        Cashier::keepPastDueSubscriptionsActive();
        
        // Set custom currency formatter
        Cashier::formatCurrencyUsing(function($amount, $currency, $locale, $options) {
            return '~' . ($amount / 100) . ' ' . $currency;
        });
    }
}
```

--------------------------------

### Query Transaction Records

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/transaction.md

Examples of common Eloquent queries for filtering transactions by status, user, subscription, or total amount.

```php
// Get recent transactions
$recent = Transaction::orderByDesc('billed_at')->limit(10)->get();

// Get transactions for a specific user
$transactions = $user->transactions()->where('status', 'completed')->get();

// Get completed transactions
$completed = Transaction::where('status', Transaction::STATUS_COMPLETED)->get();

// Get transactions for a subscription
$subTransactions = $subscription->transactions()->get();

// Get high-value transactions
$large = Transaction::where('total', '>', 50000)
    ->orderByDesc('total')
    ->get();
```

--------------------------------

### chargeAndInvoice()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/subscription.md

Adds charges and bills them immediately.

```APIDOC
## chargeAndInvoice(string|array $items)

### Description
Add charges and bill immediately (prorated if configured).

### Parameters
- **$items** (string|array) - Required - Price IDs or normalized items

### Returns
- **$this** - Returns instance for chaining
```

--------------------------------

### Webhook Payload Structure

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/webhooks.md

Example of the JSON structure for incoming webhook events, containing the event type, timestamp, and associated data.

```json
{
  "event_id": "evt_12345",
  "event_type": "subscription.created",
  "created_at": "2024-09-07T12:00:00Z",
  "data": {
    "id": "sub_12345",
    "customer_id": "ctm_12345",
    "status": "active",
    "items": [...],
    "custom_data": {...}
  }
}
```

--------------------------------

### Create a fake Cashier instance

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/cashier.md

Use Cashier::fake() to create a fake instance for testing purposes. Pass an array of arguments to configure the fake state.

```php
Cashier::fake([
    'customers' => [
        'id' => 'ctm_test_123',
        'email' => 'test@example.com',
    ],
]);
```

--------------------------------

### Pause Subscription with pause()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/subscription.md

Demonstrates pausing at the next billing cycle, immediately, or scheduling a resume date.

```php
$subscription->pause(); // Pauses at next billing
$subscription->pause(true); // Pauses immediately
$subscription->pause(false, now()->addMonths(3)); // Pauses next period, resumes in 3 months
```

--------------------------------

### Retrieve Paddle Transaction Data with asPaddleTransaction

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/transaction.md

Retrieves the complete transaction data from the Paddle API as an array. The example demonstrates accessing line item descriptions from the returned data.

```php
$paddleData = $transaction->asPaddleTransaction();
$lineItems = $paddleData['details']['line_items'];
foreach ($lineItems as $item) {
    echo $item['price']['description'];
}
```

--------------------------------

### Initialize Cashier Fake for Testing

Source: https://github.com/laravel/cashier-paddle/blob/2.x/resources/boost/skills/cashier-paddle-development/references/testing.md

Call `Cashier::fake()` once at the beginning of your tests to register HTTP and event fakes for Paddle API interactions. This sets up the testing environment.

```php
use Laravel\Paddle\Cashier;

public function test_user_can_subscribe(): void
{
    Cashier::fake();

    // Seed subscription state that would normally arrive via webhook
    $user = User::factory()->create();
    $user->customer()->create(['paddle_id' => 'cus_test123']);

    $user->subscriptions()->create([
        'type'      => 'default',
        'paddle_id' => 'sub_test123',
        'status'    => 'active',
    ])->items()->create([
        'product_id' => 'pro_basic',
        'price_id'   => 'pri_monthly',
        'status'     => 'active',
        'quantity'   => 1,
    ]);

    $this->assertTrue($user->subscribed());
    $this->assertFalse($user->subscription()->onTrial());
}
```

--------------------------------

### Listen to Specific Cashier TransactionCompleted Event

Source: https://github.com/laravel/cashier-paddle/blob/2.x/resources/boost/skills/cashier-paddle-development/references/webhooks.md

Register a listener for the `TransactionCompleted` event to perform custom actions when a transaction is successfully completed. This example shows how to retrieve an order ID from the payload and mark the order as completed.

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

// Listen to a specific Cashier event
Event::listen(TransactionCompleted::class, function (TransactionCompleted $event) {
    $orderId = $event->payload['data']['custom_data']['order_id'] ?? null;
    Order::findOrFail($orderId)->markCompleted();
});
```

--------------------------------

### Format currency amounts using Cashier::formatAmount

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/configuration.md

Demonstrates formatting currency amounts with default locales, specific locales, and custom options using PHP's Intl extension.

```php
// Default (en locale)
Cashier::formatAmount(2999, 'USD'); // "$29.99"

// Different locale
Cashier::formatAmount(2999, 'USD', 'de_DE'); // "29,99 $"

// With options
Cashier::formatAmount(2999, 'USD', 'en', [
    'min_fraction_digits' => 0, // Show no decimals
]);
```

--------------------------------

### SubscriptionBuilder checkout() Method

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/supporting-classes.md

Retrieves a checkout instance for the subscription. Accepts an optional array of price or product options.

```php
public function checkout(array $options = []): Checkout
```

```php
$checkout = $user->newSubscription(1999, 'Starter', 'starter')
    ->monthly()
    ->quantity(1)
    ->checkout();

// In view
return view('subscribe', ['checkout' => $checkout]);
```

--------------------------------

### onProduct(string $product)

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Determine if the model has a valid subscription on the given product.

```APIDOC
## onProduct(string $product)

### Description
Determine if the model has a valid subscription on the given product (any subscription type).

### Parameters
- **$product** (string) - Required - Product ID

### Returns
- **bool** - true if subscribed to product
```

--------------------------------

### asPaddleSubscription()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/subscription.md

Fetches complete subscription data from the Paddle API.

```APIDOC
## asPaddleSubscription()

### Description
Get the complete subscription data from Paddle API.

### Method
public function asPaddleSubscription(string|null $include = null): array

### Parameters
- **$include** (string|null) - Optional - Include related data ('next_transaction')

### Returns
Array of Paddle subscription data
```

--------------------------------

### swap() usage

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/subscription.md

Swaps the subscription to different prices or items, applying proration based on configuration.

```php
$subscription->swap('price_premium_monthly');
$subscription->prorate()->swap(['price_1' => 1, 'price_2' => 2]);
```

--------------------------------

### Handle Subscription Not Found Error

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/errors.md

Verify the existence of a subscription record before proceeding, throwing an exception if it is missing.

```php
// Add retry logic or wait for webhook
$subscription = Subscription::where('paddle_id', $id)->first()
    ?? throw new Exception('Subscription not found');
```

--------------------------------

### swapAndInvoice() usage

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/subscription.md

Swaps the subscription and immediately bills the prorated difference.

```php
$subscription->swapAndInvoice('price_premium_yearly');
```

--------------------------------

### Listen to SubscriptionUpdated event

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/events.md

Handles the SubscriptionUpdated event to sync pricing information in the local system cache.

```php
Event::listen(SubscriptionUpdated::class, function ($event) {
    $subscription = $event->subscription;
    
    // Sync pricing in local system
    cache()->put("sub:{$subscription->id}", $subscription, 3600);
});
```

--------------------------------

### Price Dynamic Access

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/supporting-classes.md

Demonstrates accessing price data dynamically from the Price instance.

```php
// Access any price data dynamically
$price = new Price($paddlePrice);
echo $price->id;
echo $price->description;
echo $price->product_id;
```

--------------------------------

### previewPrices($items, array $options = [])

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Fetches price previews for the customer, accounting for customer-specific context like region-based tax.

```APIDOC
## previewPrices($items, array $options = [])

### Description
Get price previews for this customer (includes customer context for personalized pricing).

### Parameters
- **$items** (array|string) - Required - Price IDs to preview
- **$options** (array) - Optional - Additional options

### Returns
- **Collection** (Collection) - A collection of PricePreview objects.

### Example
```php
$previews = $user->previewPrices('price_123');
foreach ($previews as $preview) {
    echo $preview->total();
}
```
```

--------------------------------

### Pause Subscription Immediately with pauseNow()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/subscription.md

Pauses the subscription immediately.

```php
$subscription->pauseNow();
```

--------------------------------

### Check Subscription Status by Price or Product

Source: https://github.com/laravel/cashier-paddle/blob/2.x/resources/boost/skills/cashier-paddle-development/references/subscriptions.md

Use these methods to verify if a user is subscribed to a specific price ID or product ID. Ensure the correct price or product IDs are used.

```php
$user->subscribedToPrice('pri_monthly', 'default');
$user->subscribedToProduct('pro_premium', 'default');
```

--------------------------------

### SubscriptionBuilder monthly() Method

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/supporting-classes.md

Sets the billing interval to monthly, which is the default. Returns the instance for method chaining.

```php
public function monthly(): $this
```

--------------------------------

### Format currency with formatAmount()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/cashier.md

Formats a raw amount in the smallest currency unit into a displayable string using INTL formatting.

```php
$formatted = Cashier::formatAmount(2999, 'USD');
// Returns: "$29.99"

$formatted = Cashier::formatAmount(2900, 'EUR', 'de_DE');
// Returns: "29,00 €"
```

--------------------------------

### Download invoice PDF with invoicePdf()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/transaction.md

Retrieve the URL to download the invoice PDF. Returns null if no invoice is available.

```php
if ($url = $transaction->invoicePdf()) {
    echo "<a href='$url'>Download Invoice</a>";
}
```

--------------------------------

### PricePreview price() Method

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/supporting-classes.md

Retrieves the Price object for the preview.

```php
public function price(): Price
```

--------------------------------

### Test subscription created event with Cashier::fake

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/events.md

Uses the Cashier::fake helper to assert that a subscription was created, providing a more specialized testing interface.

```php
public function test_subscription_created_event()
{
    Cashier::fake();
    
    // Create subscription...
    
    Cashier::assertSubscriptionCreated(function ($event) {
        return $event->subscription->paddle_id === 'sub_123';
    });
}
```

--------------------------------

### Managing Subscriptions

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/README.md

Check subscription status, modify plans, adjust quantities, and manage trial periods.

```php
// Check subscription status
$user->subscribed();                    // Active or trialing
$user->onTrial();                       // On trial period
$user->subscription('premium');         // Get specific type

// Modify subscription
$subscription->swap('new_price_id');    // Change price
$subscription->incrementQuantity(5);    // Add quantity
$subscription->pause();                 // Pause billing
$subscription->resume();                // Resume from pause
$subscription->cancel();                // Cancel at end of period
$subscription->cancelNow();             // Cancel immediately

// Trial management
$subscription->extendTrial(now()->addDays(30));
$subscription->activate();              // End trial now
```

--------------------------------

### SubscriptionBuilder quantity() Method

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/supporting-classes.md

Sets the quantity for the subscription. Returns the instance for method chaining.

```php
public function quantity(int $quantity): $this
```

```php
$user->newSubscription(2999, 'Pro Plan', 'premium')
    ->quantity(5)
    ->checkout();
```

--------------------------------

### Listen to All Incoming Webhooks with WebhookReceived Event

Source: https://github.com/laravel/cashier-paddle/blob/2.x/resources/boost/skills/cashier-paddle-development/references/webhooks.md

Implement a listener for the `WebhookReceived` event to capture and log all incoming webhooks from Paddle before they are processed by Cashier. This is useful for debugging and monitoring.

```php
// Listen to ALL webhooks before Cashier processes them (useful for logging)
Event::listen(WebhookReceived::class, function (WebhookReceived $event) {
    Log::info('Paddle webhook', ['type' => $event->payload['event_type']]);
});
```

--------------------------------

### Cashier::previewPrices()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/cashier.md

Preview prices for a given set of items, optionally with customer context.

```APIDOC
## Cashier::previewPrices()

### Description
Preview prices for a given set of items, optionally with customer context.

### Parameters
- **$items** (array|string) - Required - Price IDs as array or key-value pairs
- **$options** (array) - Optional - Additional options (customer_id, address, etc.)

### Returns
Collection of PricePreview objects
```

--------------------------------

### swap()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/subscription.md

Swaps the current subscription to different prices or items.

```APIDOC
## swap(string|array $items, array $options = [])

### Description
Swaps the subscription to different prices or items. Applies proration based on configured behavior.

### Parameters
- **$items** (string|array) - Required - New price IDs or items.
- **$options** (array) - Optional - Additional Paddle subscription options.

### Returns
- **$this** - Returns the subscription instance for method chaining.

### Throws
- **InvalidArgumentException** - Thrown if items are empty.
```

--------------------------------

### swapAndInvoice()

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/subscription.md

Swaps the subscription and immediately invoices the prorated difference.

```APIDOC
## swapAndInvoice(string|array $items, array $options = [])

### Description
Swaps the subscription and bills the prorated difference immediately.

### Parameters
- **$items** (string|array) - Required - New price IDs.
- **$options** (array) - Optional - Additional Paddle options.

### Returns
- **$this** - Returns the subscription instance for method chaining.
```

--------------------------------

### PricePreview Constructor

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/supporting-classes.md

The constructor for the PricePreview class.

```php
public function __construct(array $item)
```

--------------------------------

### Published Configuration File config/cashier.php

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/configuration.md

The default configuration file structure for Cashier Paddle, containing authentication keys, route paths, webhook settings, and currency defaults.

```php
return [
    // Paddle authentication keys
    'seller_id' => env('PADDLE_SELLER_ID'),
    'client_side_token' => env('PADDLE_CLIENT_SIDE_TOKEN'),
    'api_key' => env('PADDLE_AUTH_CODE') ?? env('PADDLE_API_KEY'),
    'retain_key' => env('PADDLE_RETAIN_KEY'),
    'webhook_secret' => env('PADDLE_WEBHOOK_SECRET'),
    
    // Route configuration
    'path' => env('CASHIER_PATH', 'paddle'),
    
    // Webhook configuration
    'webhook' => env('CASHIER_WEBHOOK'),
    
    // Currency configuration
    'currency' => env('CASHIER_CURRENCY', 'USD'),
    'currency_locale' => env('CASHIER_CURRENCY_LOCALE', 'en'),
    
    // Environment configuration
    'sandbox' => env('PADDLE_SANDBOX', false),
];
```

--------------------------------

### getCustomer() Getter

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/checkout.md

Retrieves the Customer instance associated with the checkout, or null if it is a guest checkout.

```php
if ($checkout->getCustomer()) {
    echo "Customer: " . $checkout->getCustomer()->name;
}
```

--------------------------------

### subscribe() Method and Usage

Source: https://github.com/laravel/cashier-paddle/blob/2.x/_autodocs/billable.md

Creates a subscription checkout instance.

```php
public function subscribe(string|array $prices, string $type = Subscription::DEFAULT_TYPE): \Laravel\Paddle\Checkout
```

```php
$checkout = $user->subscribe('price_premium_monthly', 'premium');
$checkout->returnTo(route('dashboard'))->toArray();
```
Tokens:
Raw