### Package Installation

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/configuration.md

Install the package via Composer.

```bash
composer require danestves/laravel-polar
```

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

### Run Installation Command

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/configuration.md

Publishes configuration, migrations, and views.

```bash
php artisan polar:install
```

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

### Create Subscription Example

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/billable-trait.md

Demonstrates creating single or multiple subscription types.

```php
// Single subscription type
$checkout = $user->subscribe('product_123');

// Multiple subscription types (e.g., swimming & gym memberships)
$swimming = $user->subscribe('product_swim', 'swimming');
$gym = $user->subscribe('product_gym', 'gym');
```

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

### List Customer Meters PHP Example

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/billable-trait.md

Example usage of the listCustomerMeters method.

```php
$meters = $user->listCustomerMeters();
foreach ($meters->items ?? [] as $meter) {
    echo $meter->displayName;
}
```

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

### Environment Configuration Example

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/configuration.md

Required environment variables for Polar integration.

```bash
# Polar Configuration
POLAR_ACCESS_TOKEN="polar_at_xxxxxxxxxxxxx"
POLAR_ORGANIZATION_ID="org_xxxxxxxxxxxxx"
POLAR_SERVER=sandbox
POLAR_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxx"
POLAR_PATH=polar
POLAR_CURRENCY_LOCALE=en
```

```bash
POLAR_ACCESS_TOKEN="your_access_token"
POLAR_WEBHOOK_SECRET="your_webhook_secret"
POLAR_ORGANIZATION_ID="your_org_id"
POLAR_SERVER=sandbox
```

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

### Create Checkout Example

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/billable-trait.md

Demonstrates creating a checkout with customer email and success URL redirection.

```php
$checkout = $user->checkout(['product_123', 'product_456'])
    ->withCustomerEmail('john@example.com')
    ->withSuccessUrl(url('/success'));

return $checkout; // Responsable — redirects to Polar
```

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

### Create Custom Charge Example

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/billable-trait.md

Creates a checkout for a specific amount in cents.

```php
$checkout = $user->charge(2999, ['product_123']); // $29.99
return $checkout;
```

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

### Full subscription management workflow

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/models.md

A comprehensive example demonstrating status checks, product verification, plan swapping, and seat management.

```php
$user = User::find(1);

// Get default subscription
$subscription = $user->subscription();

// Check status
if ($subscription->valid()) {
    if ($subscription->onTrial()) {
        echo "Trial ends: " . $subscription->trialEndsAt();
    } elseif ($subscription->active()) {
        echo "Active, next billing: " . $subscription->current_period_end;
    }
}

// Check product
if ($subscription->hasProduct('product_premium')) {
    // Grant premium access
}

// Manage subscription
$subscription->swap('product_business'); // Change plan
$subscription->applyDiscount('disc_upgrade'); // Apply discount
$subscription->cancel(); // Cancel with grace period

// Team seats
$seats = $subscription->seats();
$subscription->assignSeat(email: 'team@example.com');
```

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

### Manage Orders and Refunds

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/models.md

Comprehensive example demonstrating status checks, custom field access, and refund execution.

```php
$order = Order::find(1);

// Check status
if ($order->paid()) {
    echo "Order total: " . ($order->amount / 100);
} elseif ($order->refunded()) {
    echo "Order was refunded on " . $order->refunded_at;
}

// Access custom data
$data = $order->customFieldData();
echo "Customer company: " . $data['company'];

// Issue refund
$refund = $order->refund(
    amount: $order->amount / 2, // Half refund
    reason: RefundReason::Quality,
    comment: 'Partial refund for quality issues'
);

// Get invoice
$url = $order->receiptUrl();
```

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

### Verify installed SDK version

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Check the currently installed version of the Polar SDK.

```bash
composer show polar-sh/sdk | head -3
```

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

### Ingest Usage Event PHP Example

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/billable-trait.md

Example usage of the ingestUsageEvent method.

```php
$user->ingestUsageEvent('api_request', [
    'endpoint' => '/api/v1/data',
    'method' => 'GET',
    'duration_ms' => 145
]);
```

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

### Creating Separate Listener Classes

Source: https://github.com/danestves/laravel-polar/blob/main/README.md

Examples of implementing individual listener classes for specific webhook events.

```php
<?php

namespace App\Listeners;

use Danestves\LaravelPolar\Events\CheckoutCreated;

class HandleCheckoutCreated
{
    public function handle(CheckoutCreated $event): void
    {
        $checkout = $event->payload->checkout;
        // Handle checkout creation...
    }
}
```

```php
<?php

namespace App\Listeners;

use Danestves\LaravelPolar\Events\SubscriptionUpdated;

class HandleSubscriptionUpdated
{
    public function handle(SubscriptionUpdated $event): void
    {
        $subscription = $event->subscription;
        // Handle subscription update...
    }
}
```

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

### Handle SubscriptionCreated Event Listener

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/webhook-events.md

Example listener for processing SubscriptionCreated events to grant product access.

```php
namespace App\Listeners;

use Danestves\LaravelPolar\Events\SubscriptionCreated;

class HandleSubscriptionCreated
{
    public function handle(SubscriptionCreated $event): void
    {
        $subscription = $event->subscription;
        $user = $event->billable;
        
        // Grant access to product
        $user->grantAccessTo($subscription->product_id);
        
        // Send welcome email
        event(new SubscriptionStarted($user, $subscription));
    }
}
```

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

### Ingest Usage Events PHP Example

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/billable-trait.md

Example usage of the ingestUsageEvents method for batch processing.

```php
$user->ingestUsageEvents([
    [
        'eventName' => 'api_request',
        'metadata' => ['endpoint' => '/api/v1/data']
    ],
    [
        'eventName' => 'storage_used',
        'metadata' => ['bytes' => 1048576],
        'timestamp' => now()
    ]
]);
```

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

### Handle SubscriptionCanceled Event Listener

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/webhook-events.md

Example listener for sending cancellation notifications.

```php
public function handle(SubscriptionCanceled $event): void
{
    // Send "we'll miss you" email
    Mail::send(new SubscriptionCancelledNotification($event->billable));
}
```

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

### Verify working tree status

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Check for uncommitted changes before starting the upgrade process.

```bash
git status --short
```

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

### Handle SubscriptionUpdated Event Listener

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/webhook-events.md

Example listener for updating cached product information on the billable model.

```php
public function handle(SubscriptionUpdated $event): void
{
    $subscription = $event->subscription;
    
    // Update cached product on user model
    $event->billable->update([
        'current_product' => $subscription->product_id
    ]);
}
```

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

### Handle MassAssignmentException

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/errors.md

Example of a MassAssignmentException triggered by improper model configuration during creation.

```php
// If trying to mass-assign unguarded fields
$customer = Customer::create($invalidAttributes); // Throws if model not configured properly
```

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

### Update Subscription with Proration Behavior

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Example of using the updated SubscriptionUpdateProduct model with the new prorationBehavior enum.

```php
use Polar\Models\Components;

$request = new Components\SubscriptionUpdateProduct(
    productId: 'prod_xxx',
    prorationBehavior: Components\SubscriptionProrationBehavior::NextPeriod,
);

LaravelPolar::updateSubscription('sub_yyy', $request);
```

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

### Handle OrderCreated Event Listener

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/webhook-events.md

Example listener for processing OrderCreated events, demonstrating access to order and billable properties.

```php
namespace App\Listeners;

use Danestves\LaravelPolar\Events\OrderCreated;

class HandleOrderCreated
{
    public function handle(OrderCreated $event): void
    {
        // Access the order and billable
        $order = $event->order;
        $user = $event->billable;
        
        // Send confirmation email
        Mail::send(new OrderConfirmation($order));
        
        // Log purchase
        Log::info("Order {$order->polar_id} created for user {$user->id}");
    }
}
```

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

### Handle BenefitGrantCreated Event Listener

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/webhook-events.md

Example listener for handling benefit grants based on the benefit type.

```php
public function handle(BenefitGrantCreated $event): void
{
    $benefit = $event->payload->benefitGrant->benefit;
    $customer = $event->billable;
    
    // Handle benefit by type
    match ($benefit->type) {
        'license_keys' => $this->handleLicenseKeyGrant($customer, $benefit),
        'discord' => $this->handleDiscordGrant($customer, $benefit),
        default => null,
    };
}
```

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

### InvalidMetadataPayload Example

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/errors.md

Example of a metadata payload that violates API constraints.

```php
// This might exceed constraints at Polar API level
$checkout->withMetadata([
    'very_long_key_name_that_exceeds_forty_characters' => 'value', // Too long!
    'short_key' => 'a' . str_repeat('x', 501), // Value too long!
]);
```

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

### Create a Checkout Instance

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/checkout-class.md

Initializes a new checkout session with product IDs and redirect URLs.

```php
use Danestves":"LaravelPolar\\Checkout;

$checkout = Checkout::make(['product_123'])
    ->withCustomerEmail('user@example.com')
    ->withSuccessUrl(url('/success'));

return $checkout; // Redirects to Polar
```

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

### Run Migrations

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/configuration.md

Executes database migrations to create necessary tables.

```bash
php artisan migrate
```

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

### Create upgrade branch

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Switch to a new branch dedicated to the SDK upgrade.

```bash
git switch -c upgrade/polar-sdk-v0.10
```

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

### List Files

Source: https://github.com/danestves/laravel-polar/blob/main/README.md

List downloadable assets, product media, and organization avatars.

```php
$response = LaravelPolar::listFiles();
$items = $response->listResourceFileRead?->items ?? [];
```

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

### Run test suite baseline

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Verify that the current test suite passes before proceeding with the upgrade.

```bash
vendor/bin/pest --colors=never 2>&1 | tail -40
```

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

### Configure API Server Environment

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/configuration.md

Set the environment for API interactions. Use sandbox for development and production for live transactions.

```bash
POLAR_SERVER=sandbox
```

```bash
POLAR_SERVER=production
```

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

### Update Composer Packages

Source: https://github.com/danestves/laravel-polar/blob/main/docs/migration-v1-to-v2.md

After updating composer.json, run this command to install or update the specified packages.

```bash
composer update danestves/laravel-polar
```

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

### checkout(array $products, ?array $options, ?array $customerMetadata, ?array $metadata)

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/billable-trait.md

Creates a new checkout instance to sell one or more products.

```APIDOC
## checkout(array $products, ?array $options, ?array $customerMetadata, ?array $metadata)

### Description
Creates a new checkout instance to sell one or more products.

### Parameters
- **$products** (array<string>) - Required - Array of product IDs
- **$options** (array) - Optional - Checkout options (customer name/email, currency, etc.)
- **$customerMetadata** (array) - Optional - Metadata copied to the customer
- **$metadata** (array) - Optional - Checkout-only metadata

### Returns
- **Checkout** - Fluent checkout builder instance
```

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

### Get Specific Customer Meter

Source: https://github.com/danestves/laravel-polar/blob/main/README.md

Retrieve a specific meter by its ID using the LaravelPolar facade.

```php
use Danestves\LaravelPolar\LaravelPolar;

$meter = LaravelPolar::getCustomerMeter('meter-id-123');
```

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

### Get Benefit PHP Method Signature

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/billable-trait.md

Method signature for retrieving a single benefit by its ID.

```php
public function getBenefit(string $benefitId): Benefit (union type)
```

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

### listFiles()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Lists downloadable assets, product media, and organization avatars.

```APIDOC
## listFiles()

### Description
Lists downloadable assets, product media, and organization avatars.

### Signature
`public static function listFiles(string|array|null $organizationId = null, string|array|null $ids = null, ?int $page = null, ?int $limit = null): Operations\FilesListResponse`
```

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

### Run Customer tests (post-reconciliation)

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Verify the Customer model after applying necessary schema updates.

```bash
vendor/bin/pest tests/Unit/CustomerTest.php --colors=never 2>&1 | tail -10
```

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

### checkout()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/checkout-class.md

Initializes a new checkout session for a user on the server.

```APIDOC
## Method: checkout(array $products)

### Description
Creates a checkout session for the authenticated user for the specified products.

### Parameters
- **products** (array) - Required - An array of product identifiers to include in the checkout.

### Returns
- **Checkout** (Object) - Returns a checkout object that can be used to generate URLs or embed configurations.
```

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

### Run Order tests (post-reconciliation)

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Verify the Order model after applying necessary schema updates.

```bash
vendor/bin/pest tests/Unit/OrderTest.php --colors=never 2>&1 | tail -20
```

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

### swapAndInvoice(string $productId)

Source: https://github.com/danestves/laravel-polar/blob/main/README.md

Changes the user's subscription plan and immediately invoices the customer.

```APIDOC
## swapAndInvoice(string $productId)

### Description
Swaps the current subscription to a new plan and triggers an immediate invoice.

### Method
PHP SDK Method

### Parameters
- **productId** (string) - Required - The new product variant ID.
```

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

### Create Checkout on Server

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/checkout-class.md

Initializes a checkout session for a user with specific products and embed origin configuration.

```php
Route::get('/pricing', function (Request $request) {
    $checkout = $request->user()
        ->checkout(['product_123'])
        ->withEmbedOrigin(config('app.url'));

    return view('pricing', ['checkout' => $checkout]);
});
```

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

### Apply scopePaid Query Scope

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/models.md

Usage examples for filtering orders by payment status on models and relationships.

```php
$paidOrders = Order::paid()->get();
$userPaidOrders = $user->orders()->paid()->get();
```

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

### Commit Migration Documentation

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Stage and commit the newly created migration documentation file.

```bash
git add docs/migration-v0.3-to-v0.4.md
git commit -m "docs: migration notes for v0.3 → v0.4"
```

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

### Publish Updated Configuration

Source: https://github.com/danestves/laravel-polar/blob/main/docs/migration-v1-to-v2.md

Republish the configuration file to ensure you have the latest version. Use the --force flag to overwrite existing configurations if necessary.

```bash
php artisan vendor:publish --tag="polar-config" --force
```

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

### Push and create PR

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Push the feature branch and open a pull request with the summary and test plan.

```bash
git push -u origin upgrade/polar-sdk-v0.10
gh pr create --title "chore: bump polar-sh/sdk to ^0.10.0 (v0.4.0)" --body "$(cat <<'EOF'
## Summary

- Bumps `polar-sh/sdk` from `^0.7.0` to `^0.10.0`.
- Reconciles webhook payload shapes (`checkout_*`, `order_*`, `subscription_*`, `benefit_grant_*`) in `ProcessWebhook.php` against the new SDK types.
- Adds a regression test that `prorationBehavior: 'next_period'` passes through `LaravelPolar::updateSubscription`.
- Documents the upgrade in `docs/migration-v0.3-to-v0.4.md`. Bumps `LaravelPolar::VERSION` to `0.4.0`. No public-API changes for users.

## Test plan

- [ ] `vendor/bin/pest` — all tests pass
- [ ] `vendor/bin/phpstan analyse` — no errors
- [ ] `vendor/bin/pint --test` — no style violations
- [ ] Manual smoke test of a single webhook event end-to-end in a workbench app (optional, recommended)
EOF
)"
```

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

### Verify PHP Intl Extension

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/configuration.md

Check if the intl extension is installed to support locale formatting beyond the default 'en' locale.

```bash
php -m | grep intl
```

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

### Run Customer tests

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Execute unit tests for the Customer model and inspect the final output.

```bash
vendor/bin/pest tests/Unit/CustomerTest.php --colors=never 2>&1 | tail -30
```

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

### Activate a license key

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Registers a license key on a new device or machine.

```php
public static function activateLicenseKey(
    string $key,
    string $label,
    ?string $organizationId = null,
    ?array $conditions = null,
    ?array $meta = null
): Components\LicenseKeyActivationRead
```

```php
$activation = LaravelPolar::activateLicenseKey(
    key: 'LIC-XXXX-XXXX-XXXX',
    label: 'My MacBook Pro',
    meta: ['hostname' => 'macbook-pro', 'os' => 'darwin']
);
```

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

### Delete payment method via route

Source: https://github.com/danestves/laravel-polar/blob/main/docs/migration-v2.12-to-v2.13.md

Example route implementation for deleting a payment method using the user's billable instance.

```php
Route::delete('/billing/payment-methods/{pm}', function (Request $request, string $pm) {
    $request->user()->deletePaymentMethod($pm);

    return redirect()->back();
});
```

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

### Existing Checkout Creation Code

Source: https://github.com/danestves/laravel-polar/blob/main/docs/migration-v1-to-v2.md

This is an example of checkout creation code that remains compatible with Laravel Polar v2. It creates a checkout and returns a redirect response.

```php
$checkout = $user->checkout(['product_id_123']);
return $checkout->redirect();
```

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

### Checkout::make()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/checkout-class.md

Creates a new instance of the Checkout class with the specified products.

```APIDOC
## Checkout::make(array $products)

### Description
Creates a new checkout instance to begin building a session.

### Parameters
- **$products** (array<string>) - Required - Array of product IDs.

### Returns
- **self** - A new Checkout instance.
```

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

### Run Migrations

Source: https://github.com/danestves/laravel-polar/blob/main/docs/migration-v1-to-v2.md

Execute this command to apply any new database migrations introduced in v2. If you have customized migrations, you may need to republish them first.

```bash
php artisan migrate
```

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

### Run Full Webhook Suite

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Execute the entire webhook test suite to ensure no regressions were introduced in adjacent event handlers.

```bash
vendor/bin/pest tests/Feature/WebhookTest.php --colors=never 2>&1 | tail -20
```

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

### activateLicenseKey()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Activates a license key on a new device or machine.

```APIDOC
## activateLicenseKey(string $key, string $label, ?string $organizationId = null, ?array $conditions = null, ?array $meta = null)

### Description
Activates a license key on a new device or machine.

### Parameters
- **$key** (string) - Required - The license key.
- **$label** (string) - Required - Device/machine label.
- **$organizationId** (string) - Optional - Org ID.
- **$conditions** (array) - Optional - Conditions.
- **$meta** (array) - Optional - Metadata (hostname, OS, etc.).

### Returns
- Components\LicenseKeyActivationRead - The activation details.
```

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

### Publish Configuration File

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/configuration.md

Command to generate the default configuration file in the Laravel project.

```bash
php artisan vendor:publish --tag="polar-config"
```

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

### Inspect CHANGELOG

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Check the existing file content to ensure the new release section matches the established heading style.

```bash
head -20 CHANGELOG.md
```

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

### Customer Model Usage

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/models.md

Demonstrates accessing the customer relationship from a user and checking trial status.

```php
$user = User::find(1);

// Relationship access
if ($user->customer && $user->customer->polar_id) {
    echo "Polar ID: " . $user->customer->polar_id;
}

// Trial checking
if ($user->customer->onGenericTrial()) {
    echo "Trial ends: " . $user->customer->trial_ends_at;
}
```

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

### listCustomerMeters()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Lists all meters for a customer.

```APIDOC
## listCustomerMeters()

### Description
Lists all meters for a customer.

### Parameters
- **request** (Operations\CustomerMetersListRequest) - Required - The request object containing customer meter criteria.
```

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

### Create a new subscription

Source: https://github.com/danestves/laravel-polar/blob/main/README.md

Initiates a subscription checkout process using a product variant ID.

```php
use Illuminate\Http\Request;

Route::get('/subscribe', function (Request $request) {
    return $request->user()->subscribe('product_id_123');
});
```

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

### Run Order tests

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Execute unit tests for the Order model and inspect the final output.

```bash
vendor/bin/pest tests/Unit/OrderTest.php --colors=never 2>&1 | tail -40
```

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

### Search for Customer Portal references

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Use grep to identify potential usages of customer portal endpoints or organizationId filters in the source tree.

```bash
grep -rn "customerPortal" src/ tests/ --include='*.php' || true
```

```bash
grep -rn "organizationId" src/ tests/ --include='*.php' | grep -i 'portal\|customer_portal' || true
```

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

### Run Benefits and Customer Meters tests

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Executes the test suite for benefits and customer meters, piping the output to tail to inspect recent failures.

```bash
vendor/bin/pest tests/Feature/BenefitsTest.php tests/Feature/CustomerMetersTest.php --colors=never 2>&1 | tail -60
```

```bash
vendor/bin/pest tests/Feature/BenefitsTest.php tests/Feature/CustomerMetersTest.php --colors=never 2>&1 | tail -20
```

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

### Creating a Checkout Session

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Initializes a new checkout session using a configuration object.

```php
use Danestves\LaravelPolar\LaravelPolar;
use Polar\Models\Components;

$checkout = LaravelPolar::createCheckoutSession(
    new Components\CheckoutCreate(
        productPrices: ['price_id_123'],
        successUrl: 'https://example.com/success'
    )
);

echo $checkout->url;
```

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

### Run Subscription Tests

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Execute the test suite to identify failures related to the updated Subscription component fields.

```bash
vendor/bin/pest tests/Feature/SubscriptionTest.php tests/Unit/SubscriptionTest.php --colors=never 2>&1 | tail -50
```

```bash
vendor/bin/pest tests/Feature/SubscriptionTest.php tests/Unit/SubscriptionTest.php --colors=never 2>&1 | tail -30
```

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

### Run Test Suite

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Execute the Pest test suite to ensure compatibility after version changes.

```bash
vendor/bin/pest --colors=never 2>&1 | tail -5
```

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

### Run Testing and Linting

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/README.md

Commands for executing the test suite, checking coverage, and running static analysis or code style checks.

```bash
composer test          # Run tests
composer test-coverage # Run with coverage
composer lint          # PHPStan + Pint
```

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

### Create Full Checkout Workflow

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/checkout-class.md

Configure a complete checkout session including customer details, billing addresses, custom pricing, metadata, and redirect URLs.

```php
use Danestves
avelPolar\Checkout;
use Illuminate\Http\Request;
use Polar\Models\Components;

Route::post('/checkout/create', function (Request $request) {
    $checkout = Checkout::make(['product_premium', 'product_basic'])
        // Customer info
        ->withCustomerEmail($request->user()->email)
        ->withCustomerName($request->user()->name)
        ->withCustomerIpAddress($request->ip())
        
        // Billing address
        ->withCustomerBillingAddress(
            new Components\AddressInput(
                country: Components\CountryAlpha2Input::Us,
                line1: $request->input('address.line1'),
                city: $request->input('address.city'),
                state: $request->input('address.state'),
                postalCode: $request->input('address.zip')
            )
        )
        
        // Custom pricing
        ->withAmount(5000) // $50.00
        ->withCurrency(Components\PresentmentCurrency::Usd)
        
        // Discount (if provided)
        ->withDiscountId($request->input('discount_id'))
        
        // Metadata
        ->withMetadata([
            'order_type' => 'bulk_purchase',
            'team_size' => 10
        ])
        ->withCustomerMetadata([
            'customer_tier' => 'enterprise'
        ])
        ->withCustomFieldData([
            'company' => $request->input('company'),
            'seats' => $request->input('seats')
        ])
        
        // Redirects
        ->withSuccessUrl(url('/success?checkout_id={CHECKOUT_ID}'))
        ->withEmbedOrigin(config('app.url'));

    // Get URL without redirect
    $url = $checkout->url();
    
    return response()->json(['checkout_url' => $url]);
});
```

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

### user()->checkout()

Source: https://github.com/danestves/laravel-polar/blob/main/README.md

Creates a checkout session for one or more products. Returns a checkout object that can be used for redirection or embedding.

```APIDOC
## Method: user()->checkout(array $productIds)

### Description
Creates a checkout session for the authenticated user. Pass an array of product IDs to allow the user to select from multiple options.

### Parameters
- **productIds** (array) - Required - An array of product ID strings.
```

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

### Configure Webhook Path

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/configuration.md

Sets the base URL path for incoming webhooks.

```bash
POLAR_PATH=polar
```

```bash
POLAR_PATH=webhooks/polar
```

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

### Run tests with Composer

Source: https://github.com/danestves/laravel-polar/blob/main/README.md

Executes the project's test suite using the Composer test script.

```bash
composer test
```

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

### swap(string $productId)

Source: https://github.com/danestves/laravel-polar/blob/main/README.md

Changes the user's current subscription plan to a new product ID.

```APIDOC
## swap(string $productId)

### Description
Swaps the current subscription to a new plan. Billing for the new plan occurs at the next payment cycle.

### Method
PHP SDK Method

### Parameters
- **productId** (string) - Required - The new product variant ID.
```

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

### Create Single and Multi-Product Checkouts

Source: https://github.com/danestves/laravel-polar/blob/main/README.md

Use the checkout method on the user model to initiate a payment session. Pass a single product ID or an array of IDs for multiple product options.

```php
use Illuminate\Http\Request;

Route::get('/subscribe', function (Request $request) {
    return $request->user()->checkout(['product_id_123']);
});
```

```php
use Illuminate\Http\Request;

Route::get('/subscribe', function (Request $request) {
    return $request->user()->checkout(['product_id_123', 'product_id_456']);
});
```

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

### Creating a Customer

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/billable-trait.md

Initialize a new Polar customer record for the billable model.

```php
$customer = $user->createAsCustomer();
```

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

### Implementing a Listener Class

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/webhook-events.md

Define the handle method to process the event payload.

```php
namespace App\Listeners;

use Danestves\LaravelPolar\Events\OrderCreated;

class HandleOrderCreated
{
    public function handle(OrderCreated $event): void
    {
        // Access $event->billable, $event->order, $event->payload
    }
}
```

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

### Retrieve a license key

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Fetches a specific license key along with its activation history.

```php
public static function getLicenseKey(string $licenseKeyId): Components\LicenseKeyWithActivations
```

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

### Manage subscription discounts

Source: https://github.com/danestves/laravel-polar/blob/main/docs/migration-v2.7-to-v2.8.md

Use these methods on the Subscription model to apply or remove discounts. Changes take effect on the next billing cycle.

```php
$subscription->applyDiscount('disc_xxx');
$subscription->removeDiscount();
```

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

### subscribe(string $productId, string $type, ?array $options, ?array $customerMetadata, ?array $metadata)

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/billable-trait.md

Creates a subscription checkout for a product variant.

```APIDOC
## subscribe(string $productId, string $type, ?array $options, ?array $customerMetadata, ?array $metadata)

### Description
Creates a subscription checkout for a product variant.

### Parameters
- **$productId** (string) - Required - Product ID to subscribe to
- **$type** (string) - Optional - Subscription type for multiple subscriptions (default: 'default')
- **$options** (array) - Optional - Checkout options

### Returns
- **Checkout** - Fluent checkout builder instance
```

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

### createCustomerSession()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Creates a short-lived customer session for customer portal access.

```APIDOC
## createCustomerSession()

### Description
Creates a short-lived customer session for customer portal access.

### Signature
`public static function createCustomerSession(Components\CustomerSessionCustomerIDCreate|Components\CustomerSessionCustomerExternalIDCreate $request): Components\CustomerSession`

### Returns
`Components\CustomerSession` — Session token and portal URL

### Example
```php
$session = LaravelPolar::createCustomerSession(
    new Components\CustomerSessionCustomerIDCreate(
        customerId: $customer->polar_id
    )
);

echo $session->customerPortalUrl;
```
```

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

### listDiscounts()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Lists all discounts.

```APIDOC
## LaravelPolar::listDiscounts()

### Description
Lists all discounts.

### Signature
`public static function listDiscounts(?Operations\DiscountsListRequest $request = null): Operations\DiscountsListResponse`

### Parameters
- **$request** (DiscountsListRequest) - Optional - Request parameters for filtering or pagination.
```

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

### Republish Migrations

Source: https://github.com/danestves/laravel-polar/blob/main/docs/migration-v1-to-v2.md

If you have customized migration files, use this command to republish them to your application.

```bash
php artisan vendor:publish --tag="polar-migrations" --force
```

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

### Verify project integrity

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Run testing, static analysis, and linting tools to ensure the codebase remains stable after SDK changes.

```bash
vendor/bin/pest --colors=never 2>&1 | tail -30
```

```bash
vendor/bin/phpstan analyse --no-progress 2>&1 | tail -40
```

```bash
vendor/bin/pint --test
```

```bash
vendor/bin/pest --colors=never 2>&1 | tail -5 > /tmp/polar-upgrade-final.log && cat /tmp/polar-upgrade-final.log
```

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

### Project Directory Structure

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/MANIFEST.md

Visual representation of the documentation file hierarchy.

```text
output/
├── README.md                          # Main index & overview
├── configuration.md                   # Setup & environment
├── errors.md                          # Exception handling
├── types.md                           # Type definitions
├── MANIFEST.md                        # This file
└── api-reference/
    ├── laravel-polar-facade.md        # Main API surface
    ├── billable-trait.md              # Model billing methods
    ├── checkout-class.md              # Checkout builder
    ├── models.md                      # Database models
    ├── webhook-events.md              # Event handling
    └── view-components.md             # Blade rendering
```

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

### Release version tagging

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/specs/2026-05-21-polar-sdk-upgrade-and-roadmap-design.md

Automates the process of retrieving the current package version and creating a git tag for release.

```bash
git checkout main
git pull --ff-only
VERSION=$(php -r 'require "vendor/autoload.php"; echo Danestves\\LaravelPolar\\LaravelPolar::VERSION;')
git tag -a "v$VERSION" -m "Release v$VERSION"
git push origin "v$VERSION"
```

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

### Insert CHANGELOG entry

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Add the new version section to the top of the CHANGELOG file.

```markdown
## v0.4.0 - 2026-05-21

- Upgrade `polar-sh/sdk` to `^0.10.0`. Reconciled webhook payload shapes for `checkout_*`, `order_*`, `subscription_*`, and `benefit_grant_*` events; no public-API changes for users of this package.
- Documented the SDK upgrade in `docs/migration-v0.3-to-v0.4.md`.
```

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

### Run verification commands

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Execute test suites, static analysis, and style checks to ensure code integrity before submission.

```bash
vendor/bin/pest --colors=never 2>&1 | tail -10
```

```bash
vendor/bin/phpstan analyse --no-progress 2>&1 | tail -10
```

```bash
vendor/bin/pint --test
```

```bash
git status --short
```

```bash
git log --oneline main..HEAD
```

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

### WebhookHandled Access Pattern

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/webhook-events.md

Demonstrates logging the webhook type after processing.

```php
public function handle(WebhookHandled $event): void
{
    Log::info("Webhook processed: " . $event->payload['type']);
}
```

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

### withCustomerMetadata()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/checkout-class.md

Sets metadata that will be copied to the created customer record.

```APIDOC
## withCustomerMetadata(array $metadata)

### Description
Sets metadata that will be copied to the created customer record. Reserved keys (billable_id, billable_type, subscription_type) cannot be used.

### Constraints
- Same as withMetadata()

### Parameters
- **metadata** (array) - Required - An associative array of key-value pairs.

### Throws
- ReservedMetadataKeys if reserved keys are used.

### Example
```php
$checkout->withCustomerMetadata([
    'account_tier' => 'premium',
    'referrer' => 'newsletter'
]);
```
```

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

### createCheckoutLink()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Creates a reusable checkout link for a product, multiple products, or specific price.

```APIDOC
## createCheckoutLink()

### Description
Creates a reusable checkout link for a product, multiple products, or specific price.

### Parameters
- **$request** (Components\CheckoutLinkCreateProductPrice|Components\CheckoutLinkCreateProduct|Components\CheckoutLinkCreateProducts) - Required - Checkout link configuration

### Returns
Components\CheckoutLink — URL and metadata for the checkout link

### Throws
Polar\Models\Errors\APIException on API failure
```

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

### Configure Polar Environment Variables

Source: https://github.com/danestves/laravel-polar/blob/main/README.md

Set the required access token, optional organization ID, and webhook secret in your .env file.

```bash
POLAR_ACCESS_TOKEN="<your_access_token>"
```

```bash
POLAR_ORGANIZATION_ID="<your_organization_id>"
```

```bash
POLAR_WEBHOOK_SECRET="<your_webhook_secret>"
```

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

### Troubleshooting: Migration Errors

Source: https://github.com/danestves/laravel-polar/blob/main/docs/migration-v1-to-v2.md

To resolve migration errors, check the migration status, rollback if necessary, and then run the migrations again.

```bash
# Check migration status
php artisan migrate:status

# Rollback if needed
php artisan migrate:rollback

# Run migrations again
php artisan migrate
```

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

### Manage subscription trials

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/models.md

Methods for retrieving and updating trial information.

```php
public function trialEndsAt(): ?\Carbon\CarbonInterface
```

```php
public function hasExpiredTrial(): bool
```

```php
public function updateTrial(\DateTimeInterface $trialEnd): self
```

```php
$subscription->updateTrial(now()->addDays(30));
```

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

### Swap subscription with proration behavior

Source: https://github.com/danestves/laravel-polar/blob/main/docs/migration-v2.2-to-v2.3.md

Use the new proration behavior option when swapping subscription products.

```php
use Polar\\\Models\\\Components\\\SubscriptionProrationBehavior;

$subscription->swap('prod_xxx', SubscriptionProrationBehavior::NextPeriod);
```

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

### Model Configuration Methods

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Methods to configure the Eloquent models used by the package.

```APIDOC
## Model Configuration

### useCustomerModel(string $customerModel)
Sets the model class to use for customers (default: Customer).

### useSubscriptionModel(string $subscriptionModel)
Sets the model class to use for subscriptions (default: Subscription).

### useOrderModel(string $orderModel)
Sets the model class to use for orders (default: Order).
```

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

### List Products via Laravel Polar Facade

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Retrieves a paginated list of products from the organization. Returns an Operations\ProductsListResponse object.

```php
public static function listProducts(
    ?Operations\ProductsListRequest $request = null
): Operations\ProductsListResponse
```

```php
$response = LaravelPolar::listProducts();
foreach ($response->products ?? [] as $product) {
    echo $product->name;
}
```

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

### Tag and push release version

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Commands to create a git tag for the release and push it to the remote repository.

```bash
git tag -a v0.4.0 -m "Release v0.4.0"
git push origin v0.4.0
```

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

### Set Currency Locale

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/configuration.md

Configures the locale for currency formatting.

```bash
POLAR_CURRENCY_LOCALE=en
POLAR_CURRENCY_LOCALE=de
POLAR_CURRENCY_LOCALE=fr
```

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

### sdk()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Retrieves or creates a cached Polar SDK instance configured via the application's configuration files.

```APIDOC
## sdk()

### Description
Retrieves or creates a cached Polar SDK instance. The SDK is configured from config/polar.php.

### Returns
Polar\Polar — The underlying Polar SDK client instance

### Throws
Exception if POLAR_ACCESS_TOKEN is not configured
```

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

### Publish Laravel Polar Assets Individually

Source: https://github.com/danestves/laravel-polar/blob/main/README.md

Commands to publish specific package assets or run migrations manually.

```bash
php artisan vendor:publish --tag="polar-migrations"
```

```bash
php artisan vendor:publish --tag="polar-config"
```

```bash
php artisan vendor:publish --tag="polar-views"
```

```bash
php artisan migrate
```

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

### Fetch Analytics Metrics

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Retrieves revenue analytics for a specified date range and interval. Requires the Brick\DateTime library for date handling.

```php
use Brick\DateTime\LocalDate;
use Polar\Models\Components;

$metrics = LaravelPolar::getMetrics(
    new Operations\MetricsGetRequest(
        startDate: LocalDate::of(2026, 1, 1),
        endDate: LocalDate::of(2026, 1, 31),
        interval: Components\TimeInterval::Day
    )
);

foreach ($metrics->periods as $period) {
    echo $period->revenue;
}
```

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

### Creating a Checkout Link

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Generates a reusable checkout link for products or specific prices.

```php
$link = LaravelPolar::createCheckoutLink(
    new Components\CheckoutLinkCreateProduct(
        productId: 'product_123',
        paymentProcessor: 'stripe'
    )
);

// Share $link->url anywhere
```

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

### user()->charge()

Source: https://github.com/danestves/laravel-polar/blob/main/README.md

Creates a checkout session with a custom price override for a specific product.

```APIDOC
## Method: user()->charge(int $amount, array $productIds)

### Description
Overrides the default price of a product during the checkout process.

### Parameters
- **amount** (int) - Required - The custom price amount.
- **productIds** (array) - Required - An array containing the product ID.
```

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

### Test Subscription Management

Source: https://github.com/danestves/laravel-polar/blob/main/docs/migration-v1-to-v2.md

Verify subscription status checks and retrieval. Ensure that the `subscribed()` method returns a boolean and that subscription retrieval returns a `Subscription` instance.

```php
// Test subscription status checks
assert($user->subscribed() === true || $user->subscribed() === false);

// Test subscription retrieval
$subscription = $user->subscription();
assert($subscription instanceof \Danestves\LaravelPolar\Subscription);
```

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

### Test Checkout Flow

Source: https://github.com/danestves/laravel-polar/blob/main/docs/migration-v1-to-v2.md

Test the checkout creation and redirect process. Ensure that a checkout instance is created and a redirect response is returned.

```php
// Test checkout creation
$checkout = $user->checkout(['product_id']);
assert($checkout instanceof \Danestves\LaravelPolar\Checkout);

// Test checkout redirect
$response = $checkout->redirect();
assert($response instanceof \Illuminate\Http\RedirectResponse);
```

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

### listLicenseKeys()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Lists license keys (admin-scoped, requires org-scoped access token).

```APIDOC
## listLicenseKeys(string|array|null $organizationId = null, string|array|null $benefitId = null, ?int $page = null, ?int $limit = null)

### Description
Lists license keys (admin-scoped, requires org-scoped access token).

### Parameters
- **$organizationId** (string|array) - Optional - Organization ID.
- **$benefitId** (string|array) - Optional - Benefit ID.
- **$page** (int) - Optional - Page number.
- **$limit** (int) - Optional - Limit per page.

### Returns
- Operations\LicenseKeysListResponse - A list of license keys.
```

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

### Manage License Keys

Source: https://github.com/danestves/laravel-polar/blob/main/README.md

Perform administrative actions on license keys using the LaravelPolar facade.

```php
use Danestves\LaravelPolar\LaravelPolar;
use Polar\Models\Components;

LaravelPolar::listLicenseKeys();                                  // optional filters
LaravelPolar::getLicenseKey('lk_xxx');                            // LicenseKeyWithActivations
LaravelPolar::updateLicenseKey('lk_xxx', new Components\LicenseKeyUpdate(
    limitActivations: 10,
));
```

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

### charge(int $amount, array $products, ?array $options, ?array $customerMetadata, ?array $metadata)

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/billable-trait.md

Creates a checkout with a custom price in cents.

```APIDOC
## charge(int $amount, array $products, ?array $options, ?array $customerMetadata, ?array $metadata)

### Description
Creates a checkout with a custom price (in cents).

### Parameters
- **$amount** (int) - Required - Amount in cents (e.g., 10000 = $100.00)
- **$products** (array<string>) - Required - Product IDs

### Returns
- **Checkout** - Fluent checkout builder instance
```

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

### Verify License Keys

Source: https://github.com/danestves/laravel-polar/blob/main/README.md

Validate and manage license key activations from end-user machines.

```php
// Validate a key (optionally bound to a specific activation):
LaravelPolar::validateLicenseKey(
    key: 'LIC-XXXX-XXXX-XXXX',
    activationId: 'act_xxx',
);

// Activate a license on a new device:
$activation = LaravelPolar::activateLicenseKey(
    key: 'LIC-XXXX-XXXX-XXXX',
    label: 'My MacBook Pro',
    meta: ['hostname' => 'macbook-pro', 'os' => 'darwin'],
);

// Deactivate an activation:
LaravelPolar::deactivateLicenseKey(
    key: 'LIC-XXXX-XXXX-XXXX',
    activationId: 'act_xxx',
);
```

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

### View Directory Structure

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/view-components.md

Displays the file structure created after publishing the Polar views.

```text
resources/views/vendor/polar/
├── components/
│   └── button.blade.php
└── js.blade.php
```

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

### listCustomerMeters(?string $meterId)

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/billable-trait.md

Lists all meters for the customer, with an optional filter for a specific meter ID.

```APIDOC
## listCustomerMeters(?string $meterId)

### Description
Lists all meters for this customer, optionally filtered to a specific meter. Throws Exception if customer not yet created.

### Parameters
- **$meterId** (string) - Optional - The specific meter ID to filter by
```

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

### listProducts()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Lists all products in the organization using the LaravelPolar facade.

```APIDOC
## listProducts(?Operations\ProductsListRequest $request = null)

### Description
Lists all products in the organization.

### Parameters
- **$request** (Operations\ProductsListRequest) - Optional - Request parameters for listing products

### Returns
- **Operations\ProductsListResponse** - Paginated products
```

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

### Publish Package Views

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/configuration.md

Use this Artisan command to copy the package's Blade views into your application's resources directory for customization.

```bash
php artisan vendor:publish --tag="polar-views"
```

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

### Set customer-level metadata

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/checkout-class.md

Attaches metadata that propagates to the created customer record. Throws ReservedMetadataKeys if reserved keys are used.

```php
$checkout->withCustomerMetadata([
    'account_tier' => 'premium',
    'referrer' => 'newsletter'
]);
```

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

### Cancel and resume subscription

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/models.md

Methods to manage the subscription lifecycle.

```php
public function cancel(): self
```

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

```php
public function resume(): self
```

```php
if ($subscription->onGracePeriod()) {
    $subscription->resume();
}
```

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

### listCheckoutLinks()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Lists all checkout links with optional filtering and pagination.

```APIDOC
## listCheckoutLinks()

### Description
Lists all checkout links with optional filtering and pagination.

### Parameters
- **$request** (Operations\CheckoutLinksListRequest) - Optional - Filtering and pagination options

### Returns
Operations\CheckoutLinksListResponse — Paginated results
```

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

### getLicenseKey()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Retrieves a license key with its activation history.

```APIDOC
## getLicenseKey(string $licenseKeyId)

### Description
Retrieves a license key with its activation history.

### Parameters
- **$licenseKeyId** (string) - Required - The ID of the license key.

### Returns
- Components\LicenseKeyWithActivations - The license key details.
```

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

### Register Custom Models

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/configuration.md

Override default package models by calling these methods within a service provider's boot method.

```php
use Danestves\LaravelPolar\LaravelPolar;

public function boot(): void
{
    LaravelPolar::useCustomerModel('App\\Models\\PolarCustomer');
    LaravelPolar::useSubscriptionModel('App\\Models\\PolarSubscription');
    LaravelPolar::useOrderModel('App\\Models\\PolarOrder');
}
```

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

### Define CheckoutCreate Component

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/types.md

Input object for creating a new checkout session.

```php
class CheckoutCreate
{
    public array $productPrices; // Required: array of product/price IDs
    public ?string $successUrl = null;
    public ?string $customerName = null;
    public ?string $customerEmail = null;
    public ?string $customerId = null;
    public ?string $customerExternalId = null;
    // ... many other optional fields
}
```

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

### createDiscount()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Creates a new discount code.

```APIDOC
## LaravelPolar::createDiscount()

### Description
Creates a new discount code.

### Signature
`public static function createDiscount(Components\DiscountFixedOnceForeverDurationCreate|... $request): Discount`

### Parameters
- **$request** (DiscountCreate*) - Required - The discount creation request object.
```

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

### CustomerCreated Access Pattern

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/webhook-events.md

Demonstrates how to access the customer payload within an event handler.

```php
public function handle(CustomerCreated $event): void
{
    $customer = $event->payload->customer;
}
```

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

### Log exceptions in Laravel

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/errors.md

Use the Log facade to record detailed exception information including the message, file, line, and stack trace.

```php
use Illuminate\Support\Facades\Log;

try {
    // API call
} catch (\Exception $e) {
    Log::error('Polar operation failed', [
        'exception' => get_class($e),
        'message' => $e->getMessage(),
        'code' => $e->getCode(),
        'file' => $e->getFile(),
        'line' => $e->getLine(),
        'trace' => $e->getTraceAsString(),
    ]);
}
```

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

### Commit Subscription Model Changes

Source: https://github.com/danestves/laravel-polar/blob/main/docs/superpowers/plans/2026-05-21-polar-sdk-upgrade-baseline.md

Stage and commit the updated model and test files after reconciling with the SDK.

```bash
git add src/Subscription.php src/LaravelPolar.php tests/Feature/SubscriptionTest.php tests/Unit/SubscriptionTest.php
git commit -m "fix(subscription): reconcile model with polar-sh/sdk v0.10 response shape"
```

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

### listBenefits()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/api-reference/laravel-polar-facade.md

Lists all benefits for an organization.

```APIDOC
## listBenefits()

### Description
Lists all benefits for an organization.

### Signature
`public static function listBenefits(Operations\BenefitsListRequest $request): Operations\BenefitsListResponse`
```