Laravel Polar

https://github.com/danestves/laravel-polar
Admin
A Laravel package to seamlessly integrate Polar.sh subscriptions and payments, providing tools for...
Tokens:81,323
Snippets:1,123
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### get() usage examples

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Examples of using the get method for basic requests and requests with query parameters.

```php
$org = $client->get('/v1/organizations/org_xxx');

// With query params
$products = $client->get('/v1/products/', ['limit' => 50, 'page' => 1]);
```

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

### activateLicenseKey() Usage Example

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

Example of activating a license key with metadata.

```php
$activation = LaravelPolar::activateLicenseKey(
    key: 'LIC-XXXX-XXXX-XXXX',
    label: 'Home MacBook Pro',
    meta: ['hostname' => 'mbp.local', 'os' => 'darwin'],
);

echo $activation->id; // Use this to deactivate later
```

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

### listCustomerLicenseKeys() usage example

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

Example of listing and displaying a customer's license keys.

```php
$session = LaravelPolar::createCustomerSession(['customer_id' => 'cust_xxx']);
$keys = LaravelPolar::listCustomerLicenseKeys($session->token);

foreach ($keys as $key) {
    echo $key->key;
}
```

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

### getLicenseKey() Usage Example

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

Example of retrieving a license key and iterating over its activations.

```php
$key = LaravelPolar::getLicenseKey('lk_xxx');

foreach ($key->activations as $activation) {
    echo $activation->label;
}
```

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

### subscription() usage examples

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

Examples for retrieving default or named subscription types.

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

// Get named subscription type
$swimming = $user->subscription('swimming');
$gym = $user->subscription('gym');

if ($sub) {
    echo $sub->status;
}
```

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

### listLicenseKeys() Usage Example

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

Example of listing license keys with a limit filter.

```php
$keys = LaravelPolar::listLicenseKeys(['limit' => 100]);

foreach ($keys as $key) {
    echo $key->key;
}
```

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

### listCheckoutLinks() usage example

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

Example showing how to list checkout links and iterate through the results.

```php
$links = LaravelPolar::listCheckoutLinks(['limit' => 50]);

foreach ($links as $link) {
    echo $link->url;
}
```

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

### updateLicenseKey() Usage Example

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

Example of updating the activation limit for a license key.

```php
$key = LaravelPolar::updateLicenseKey('lk_xxx', [
    'limit_activations' => 10,
]);
```

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

### listProducts() usage examples

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

Examples showing how to fetch products, iterate through the results, check for additional pages, and convert the result to a collection.

```php
use Danestves\LaravelPolar\LaravelPolar;

// Get first page of products
$page = LaravelPolar::listProducts(['limit' => 20, 'page' => 1]);

foreach ($page as $product) {
    echo $product->name; // string
    echo $product->id;   // string
}

// Check pagination
if ($page->hasMorePages()) {
    $nextPage = LaravelPolar::listProducts(['page' => 2]);
}

// Convert to collection
$collection = $page->collect();
```

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

### Check incomplete setup with incomplete()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/03-subscription-order-models.md

Verifies if the subscription setup is currently incomplete, typically awaiting payment confirmation.

```php
if ($subscription->incomplete()) {
    echo "Setup not finished";
}
```

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

### subscriptions() usage examples

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

Examples for retrieving and iterating over subscriptions for a billable model.

```php
// Get all subscriptions
$subs = $user->subscriptions()->get();

// Get active subscriptions only
$active = $user->subscriptions()->where('status', 'active')->get();

// Iterate
foreach ($user->subscriptions() as $sub) {
    echo $sub->id;
}
```

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

### createCheckoutLink() usage examples

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

Examples showing how to create checkout links for a single product or multiple products.

```php
use Danestves\LaravelPolar\Data;

// Single product link
$link = LaravelPolar::createCheckoutLink(new Data\CheckoutLinkCreateProduct(
    productId: 'prod_123',
    paymentProcessor: 'stripe',
));

echo $link->url; // Share this anywhere

// Multiple products (customer chooses)
$link = LaravelPolar::createCheckoutLink(new Data\CheckoutLinkCreateProducts(
    productIds: ['prod_123', 'prod_456'],
    paymentProcessor: 'stripe',
));
```

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

### createRefund() usage example

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

Example of creating a refund using an array of refund details.

```php
use Danestves\LaravelPolar\Enums\RefundCreateReason;

$refund = LaravelPolar::createRefund([
    'order_id' => 'ord_xxx',
    'amount' => 2500, // cents
    'reason' => RefundCreateReason::Fraudulent,
    'comment' => 'Fraudulent transaction',
]);
```

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

### Charge method usage examples

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

Examples showing how to charge a custom amount and how to include metadata with the charge.

```php
// Charge custom amount instead of default price
$checkout = $user->charge(5000, 'product_123'); // $50.00
return $checkout->redirect();

// With metadata
$checkout = $user->charge(5000, 'product_123')
    ->withMetadata(['discount_reason' => 'loyal_customer']);
```

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

### Create customer session examples

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

Examples showing how to create a session by Polar customer ID or external customer ID, and how to use the resulting token to list payment methods.

```php
// Create session by Polar customer ID
$session = LaravelPolar::createCustomerSession([
    'customer_id' => 'cust_xxx',
]);

// Or by external customer ID (from your system)
$session = LaravelPolar::createCustomerSession([
    'external_customer_id' => 'user_123',
]);

// Use the token to access customer portal routes
$methods = LaravelPolar::listCustomerPaymentMethods($session->token);
```

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

### subscribedToProduct() usage examples

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

Examples for verifying product subscriptions across different subscription types.

```php
if ($user->subscribedToProduct('product_premium')) {
    echo "User has active premium subscription";
}

// Check named subscription type
if ($user->subscribedToProduct('product_gym', 'gym')) {
    echo "User subscribed to gym plan";
}
```

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

### PolarClient Constructor Example

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Example of instantiating a PolarClient using a sandbox API base URL.

```php
$client = new PolarClient(
    accessToken: 'pat_xxx',
    baseUrl: 'https://sandbox-api.polar.sh',
);
```

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

### updateSubscription() usage examples

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

Examples demonstrating how to upgrade a subscription product and how to remove a discount by setting keepNulls to true.

```php
// Upgrade a subscription to a different product
$subscription = LaravelPolar::updateSubscription('sub_xxx', [
    'product_id' => 'prod_new_plan',
]);

// Remove a discount (use keepNulls to actually send the null)
$subscription = LaravelPolar::updateSubscription(
    'sub_xxx',
    ['discount_id' => null],
    keepNulls: true
);
```

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

### Checkout method usage examples

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

Examples demonstrating single product checkout, multiple product selection, fluent chaining, and embedding in a view.

```php
// Single product
$checkout = $user->checkout('product_123');
return $checkout; // Responsable — returns redirect to Polar

// Multiple products (customer picks one)
$checkout = $user->checkout(['product_123', 'product_456']);

// Fluent chain
return $user->checkout('product_123')
    ->withSuccessUrl('https://app.local/success')
    ->withMetadata(['plan' => 'premium'])
    ->redirect();

// Use in view
$checkout = $user->checkout('product_123')->withEmbedOrigin(config('app.url'));
return view('billing', ['checkout' => $checkout]);
```

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

### getOrder() usage example

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

Example of retrieving an order and accessing its amount property.

```php
$order = LaravelPolar::getOrder('ord_xxx');
echo $order->amount;
```

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

### listCustomerPaymentMethods() usage example

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

Example of listing payment methods and iterating through them to display type and card details.

```php
$session = LaravelPolar::createCustomerSession(['customer_id' => 'cust_xxx']);
$methods = LaravelPolar::listCustomerPaymentMethods($session->token);

foreach ($methods as $method) {
    echo $method->type; // 'card', etc.
    if ($method->type === 'card') {
        echo $method->last4;
    }
}
```

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

### Check expired incomplete setup with incompleteExpired()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/03-subscription-order-models.md

Determines if the subscription setup has expired and can no longer be resumed.

```php
if ($subscription->incompleteExpired()) {
    echo "Setup expired, cannot be resumed";
}
```

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

### validateLicenseKey() Usage Example

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

Examples of validating a license key with basic and specific activation checks.

```php
try {
    $validated = LaravelPolar::validateLicenseKey('LIC-XXXX-XXXX-XXXX');
    echo "Valid license";
} catch (PolarApiError $e) {
    echo "Invalid or expired: " . $e->message;
}

// Validate with specific activation
$validated = LaravelPolar::validateLicenseKey(
    'LIC-XXXX-XXXX-XXXX',
    activationId: 'act_xxx',
);
```

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

### Run polar:install command

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

Execute the polar:install command to publish configuration, migrations, and views, and optionally run migrations.

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

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

### PolarClient::page() usage example

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Example of fetching a product page and iterating through the results.

```php
$page = $client->page(
    '/v1/products/',
    Data\Product::class,
    ['limit' => 50, 'page' => 1],
);

foreach ($page as $product) {
    echo $product->name;
}

if ($page->hasMorePages(1)) {
    // Fetch next page
}
```

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

### createCheckoutSession() usage examples

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

Examples of creating a checkout session using either a data object for a single product or an array for more complex configurations including metadata and customer details.

```php
use Danestves\LaravelPolar\LaravelPolar;
use Danestves\LaravelPolar\Data;

// Create a simple single-product checkout
$checkout = LaravelPolar::createCheckoutSession(new Data\CheckoutCreate(
    products: ['product_123'],
));

echo $checkout->url; // Redirect user here

// Or with custom metadata and customer info
$checkout = LaravelPolar::createCheckoutSession([
    'products' => ['product_123'],
    'customer_name' => 'John Doe',
    'customer_email' => 'john@example.com',
    'metadata' => ['user_id' => 123],
    'success_url' => 'https://app.local/billing/success',
]);
```

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

### get()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Sends a GET request to the specified API path.

```APIDOC
## get(string $path, array $query = [], ?string $token = null)

### Description
Sends a GET request to the specified API path and returns the decoded JSON response.

### Parameters
- **path** (string) - Required - API path (e.g., "/v1/products/")
- **query** (array) - Optional - Query parameters
- **token** (string|null) - Optional - Override access token

### Returns
- **array** - Decoded JSON response

### Throws
- **PolarApiError** - On non-2xx response
```

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

### getCheckoutLink() usage example

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

Example showing how to retrieve and display the URL of a specific checkout link.

```php
$link = LaravelPolar::getCheckoutLink('cl_xxx');
echo $link->url;
```

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

### onTrial() usage example

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

Example for checking trial status and accessing trial end date.

```php
if ($user->onTrial()) {
    echo "User is on trial";
    echo "Trial ends at: " . $user->subscription()->trialEndsAt();
}
```

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

### createDiscount() usage examples

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

Demonstrates creating both percentage-based and fixed-amount discounts using the LaravelPolar facade.

```php
use Danestves\LaravelPolar\Data;
use Danestves\LaravelPolar\Enums\DiscountDuration;

// Percentage discount
$discount = LaravelPolar::createDiscount(new Data\DiscountPercentageCreate(
    name: 'Black Friday 50%',
    duration: DiscountDuration::Once,
    basisPoints: 5000, // 50.00%
    organizationId: 'org_xxx',
));

// Fixed discount
$discount = LaravelPolar::createDiscount(new Data\DiscountFixedCreate(
    name: '\$10 Off',
    duration: DiscountDuration::Forever,
    amountInCents: 1000,
    organizationId: 'org_xxx',
));
```

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

### get() method definition

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Method signature for sending a GET request to the API.

```php
public function get(string $path, array $query = [], ?string $token = null): array
```

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

### listSeats() usage example

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

Example of listing seats and accessing seat availability and individual seat details.

```php
$seats = LaravelPolar::listSeats(subscriptionId: 'sub_xxx');

echo $seats->totalSeats;     // Total seats in plan
echo $seats->availableSeats; // Unassigned seats

foreach ($seats->seats as $seat) {
    echo $seat->email;
    echo $seat->status;
}
```

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

### subscribed() usage examples

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

Examples for checking active subscriptions by type or product ID.

```php
// Check if user has any active subscription
if ($user->subscribed()) {
    echo "User has active subscription";
}

// Check for specific subscription type
if ($user->subscribed('premium')) {
    echo "User has premium subscription";
}

// Check for specific product
if ($user->subscribed('default', 'product_123')) {
    echo "User subscribed to product_123";
}
```

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

### Create discount percentage

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

Example of creating a percentage discount using the new DiscountPercentageCreate class.

```php
new Data\DiscountPercentageCreate(
    name: 'Black Friday 50%',
    duration: DiscountDuration::Once,
    basisPoints: 5000,
    organizationId: 'org_xxx',
);
```

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

### listRefunds() usage example

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

Example of listing refunds filtered by order ID and iterating through the results.

```php
$refunds = LaravelPolar::listRefunds(['order_id' => 'ord_xxx']);

foreach ($refunds as $refund) {
    echo $refund->amount;
}
```

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

### delete() usage example

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Example of using the delete method to remove a resource.

```php
$client->delete('/v1/discounts/disc_xxx');
```

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

### assignSeat() usage examples

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

Examples of assigning seats by email, customer ID, or using a Data\SeatAssign object with metadata.

```php
// Assign by email (sends invitation)
$seat = LaravelPolar::assignSeat([
    'subscription_id' => 'sub_xxx',
    'email' => 'alice@example.com',
]);

// Or by customer ID
$seat = LaravelPolar::assignSeat([
    'subscription_id' => 'sub_xxx',
    'customer_id' => 'cust_yyy',
]);

// With metadata
$seat = LaravelPolar::assignSeat(new Data\SeatAssign(
    subscriptionId: 'sub_xxx',
    email: 'alice@example.com',
    metadata: ['role' => 'admin'],
));
```

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

### Install Laravel Polar via Composer and Artisan

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

Run these commands to install the package and publish necessary configuration files.

```bash
composer require danestves/laravel-polar
php artisan polar:install
```

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

### post() usage examples

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Examples of using the post method with an array body or a Spatie Data object.

```php
$checkout = $client->post('/v1/checkouts/', [
    'products' => ['prod_123'],
    'customer_email' => 'john@example.com',
]);

// With Spatie Data object
$checkout = $client->post('/v1/checkouts/', new Data\CheckoutCreate(...));
```

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

### Page::items iteration example

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Example of iterating over the items property of a Page instance.

```php
foreach ($page->items as $product) {
    echo $product->name;
}
```

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

### 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
```

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

### withReturnUrl() usage example

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Demonstrates how to set the return URL for the checkout back button.

```php
$checkout->withReturnUrl('https://app.local/pricing');
```

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

### withSuccessUrl() usage examples

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Shows how to set a success URL, including the use of the {CHECKOUT_ID} placeholder for dynamic query parameters.

```php
$checkout->withSuccessUrl('https://app.local/billing/success');

// With checkout ID parameter
$checkout->withSuccessUrl('https://app.local/success?checkout_id={CHECKOUT_ID}');
```

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

### updateCheckoutLink() usage example

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

Example showing how to update a checkout link using its ID and an update payload.

```php
$link = LaravelPolar::updateCheckoutLink('cl_xxx', [
    'label' => 'Black Friday Offer',
]);
```

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

### listBenefits() usage example

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

Retrieves a list of benefits with a limit and iterates through them.

```php
$benefits = LaravelPolar::listBenefits(['limit' => 50]);

foreach ($benefits as $benefit) {
    echo $benefit->type; // e.g., 'custom', 'discord', 'github_repository'
}
```

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

### Page iteration example

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Demonstrating that the Page class is directly iterable.

```php
foreach ($page as $item) {
    echo $item->name;
}
```

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

### createBenefit() usage examples

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

Demonstrates creating custom benefits and Discord role benefits using the LaravelPolar facade.

```php
use Danestves\LaravelPolar\Data;

// Create a custom benefit
$benefit = LaravelPolar::createBenefit(new Data\BenefitCustomCreate(
    description: 'Premium Support',
    organizationId: 'org_xxx',
    properties: new Data\BenefitCustomCreateProperties(),
));

// Create a Discord role benefit
$benefit = LaravelPolar::createBenefit(new Data\BenefitDiscordCreate(
    description: 'Premium Members Discord Role',
    organizationId: 'org_xxx',
    properties: new Data\BenefitDiscordCreateProperties(
        guildId: '123456789',
        roleId: '987654321',
    ),
));
```

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

### getBenefit() usage example

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

Fetches a benefit by ID and outputs its description.

```php
$benefit = LaravelPolar::getBenefit('benefit_123');
echo $benefit->description;
```

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

### Invoice Download Route

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

Example route to trigger an invoice download.

```php
Route::get('/orders/{order}/invoice', function (Order $order) {
    return $order->downloadInvoice(); // throws RuntimeException if no URL is available
});
```

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

### listDiscounts() usage example

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

Retrieves a paginated list of discounts and iterates through them.

```php
$discounts = LaravelPolar::listDiscounts();

foreach ($discounts as $discount) {
    echo $discount->name;
}
```

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

### listBenefitGrants() usage example

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

Lists grants for a benefit and iterates through them to display customer IDs.

```php
$grants = LaravelPolar::listBenefitGrants('benefit_xxx');

foreach ($grants as $grant) {
    echo $grant->customerId; // Customer who has this benefit
}
```

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

### getOrderInvoiceUrl() usage example

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

Example of requesting an invoice URL and handling the case where it might still be generating.

```php
$session = LaravelPolar::createCustomerSession(['customer_id' => 'cust_xxx']);
$url = LaravelPolar::getOrderInvoiceUrl($session->token, 'ord_xxx');

if ($url) {
    echo "Invoice ready: $url";
} else {
    echo "Still generating...";
}
```

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

### PolarClient resolveBaseUrl Usage Examples

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Demonstrates resolving base URLs using 'sandbox', 'production' aliases, or providing a custom URL directly.

```php
// Returns 'https://sandbox-api.polar.sh'
PolarClient::resolveBaseUrl('sandbox');

// Returns 'https://api.polar.sh'
PolarClient::resolveBaseUrl('production');

// Returns exact URL
PolarClient::resolveBaseUrl('http://localhost:8000');
```

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

### patch() usage examples

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Examples of using the patch method for updates and clearing fields using keepNulls.

```php
$subscription = $client->patch('/v1/subscriptions/sub_xxx', [
    'product_id' => 'prod_new',
]);

// Clear a field with keepNulls
$subscription = $client->patch(
    '/v1/subscriptions/sub_xxx',
    ['discount_id' => null],
    keepNulls: true
);
```

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

### deleteCheckoutLink() usage example

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

Example showing how to delete a checkout link by its ID.

```php
LaravelPolar::deleteCheckoutLink('cl_xxx');
```

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

### Install package via Composer

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

Install the Laravel Polar package using the Composer dependency manager.

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

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

### Accessing the billable model

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/03-subscription-order-models.md

Example of retrieving the billable model, such as a User, from a subscription instance.

```php
$user = $subscription->billable; // e.g., User model
```

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

### resendSeatInvitation() usage example

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

Example of resending an invitation for a specific seat ID.

```php
$seat = LaravelPolar::resendSeatInvitation('seat_xxx');
```

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

### getDiscount() usage example

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

Fetches a specific discount by ID and accesses its properties.

```php
$discount = LaravelPolar::getDiscount('disc_xxx');
echo $discount->name;
```

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

### Query incomplete subscriptions with scopeIncomplete()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/03-subscription-order-models.md

Use this scope to retrieve all subscriptions that have an incomplete setup.

```php
$incomplete = Subscription::query()->incomplete()->get();
```

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

### List and get organizations

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

Retrieve a list of organizations or details for a specific organization.

```php
$orgs = LaravelPolar::listOrganizations();
$org  = LaravelPolar::getOrganization('org_xxx'); // Data\Organization
```

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

### Use SubscriptionStatus Enum

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

Example of checking a subscription status against the SubscriptionStatus enum cases.

```php
use Danestves\LaravelPolar\Enums\SubscriptionStatus;

if ($subscription->status === SubscriptionStatus::Active) {
    echo "User has active subscription";
}

if ($subscription->status === SubscriptionStatus::Trialing) {
    echo "On trial until: " . $subscription->trial_ends_at;
}
```

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

### withSubscriptionId() usage example

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Demonstrates how to call the withSubscriptionId method with a subscription ID string.

```php
$checkout->withSubscriptionId('sub_xxx');
```

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

### Accessing the billable model

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/03-subscription-order-models.md

Example of accessing the billable model (e.g., User) from an order instance.

```php
$user = $order->billable; // e.g., User model
```

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

### HandleOrderCreated listener example

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

Implement a listener to react to the OrderCreated event, such as sending a confirmation email to the user.

```php
namespace App\\\Listeners;

use Danestves\\\LaravelPolar\\\Events\\\OrderCreated;

class HandleOrderCreated
{
    public function handle(OrderCreated $event): void
    {
        $order = $event->order;
        $user = $event->billable;

        // Send confirmation email
        Mail::to($user->email)->send(new OrderConfirmation($order));
    }
}
```

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

### revokeSeat() usage example

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

Example of revoking a seat assignment using a seat ID.

```php
$seat = LaravelPolar::revokeSeat('seat_xxx');
```

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

### 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
```

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

### Run migrations

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

Execute the database migrations.

```bash
php artisan migrate
```

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

### Avoiding ReservedMetadataKeys Errors

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

Provides examples of valid metadata usage versus the use of reserved keys that trigger exceptions.

```php
// Good: use your own keys
$checkout->withMetadata([
    'user_id' => '123',
    'source' => 'email',
]);

// Good: customer metadata (different space)
$checkout->withCustomerMetadata([
    'industry' => 'SaaS',
]);

// Bad: reserved keys
$checkout->withMetadata([
    'billable_id' => '123',  // Reserved!
]);
```

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

### Publish and run migrations

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

Commands to publish and execute the database migrations required for the v3 update.

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

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

### Creating a Checkout via make()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Use the static factory method to create a new checkout instance with a list of product IDs.

```php
$checkout = Checkout::make(['product_123', 'product_456']);
```

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

### deleteCustomerPaymentMethod() usage example

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

Example of deleting a specific payment method using a customer session token.

```php
$session = LaravelPolar::createCustomerSession(['customer_id' => 'cust_xxx']);
LaravelPolar::deleteCustomerPaymentMethod($session->token, 'pm_xxx');
```

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

### __construct()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Initializes a new instance of the PolarClient with authentication credentials and configuration settings.

```APIDOC
## __construct(string $accessToken, string $baseUrl, string $version, ?int $timeout)

### Description
Creates an authenticated HTTP client for interacting with the Polar API.

### Parameters
- **accessToken** (string) - Required - Polar API access token.
- **baseUrl** (string) - Optional - Base URL (defaults to production URL).
- **version** (string) - Optional - Polar API version (defaults to 2026-04).
- **timeout** (int|null) - Optional - Request timeout in seconds.

### Example
```php
$client = new PolarClient(
    accessToken: 'pat_xxx',
    baseUrl: 'https://sandbox-api.polar.sh',
);
```
```

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

### 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
$files = LaravelPolar::listFiles();   // Page<Data\FileRead>

foreach ($files as $file) {
    echo $file->name;
}
```

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

### 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
```

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

### Publish configuration

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

Manually publish the package configuration file.

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

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

### 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
```

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

### Create a Subscription

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

Initiate a new subscription checkout using the billable model and a product variant ID.

```php
use Illuminate\Http\Request;

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

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

### deleteBenefit() usage example

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

Deletes a benefit using its ID.

```php
LaravelPolar::deleteBenefit('benefit_xxx');
```

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

### updateBenefit() usage example

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

Updates the description of an existing benefit.

```php
$benefit = LaravelPolar::updateBenefit('benefit_xxx', [
    'description' => 'Updated Premium Support',
]);
```

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

### 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
```

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

### 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"
```

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

### List Benefit Grants

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

Get all grants associated with a specific benefit.

```php
$grants = $user->listBenefitGrants('benefit-id-123');
```

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

### activateLicenseKey() Method Definition

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

Method signature for activating a license on a new device.

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

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

### Get Specific Benefit

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

Retrieve details for a specific benefit by its ID.

```php
$benefit = $user->getBenefit('benefit-id-123');
```

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

### Usage of DiscountType

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

Demonstrates how to create percentage and fixed amount discounts using the LaravelPolar facade.

```php
use Danestves\LaravelPolar\Data;

// Percentage discount
$discount = LaravelPolar::createDiscount(new Data\DiscountPercentageCreate(
    name: '50% Off',
    basisPoints: 5000,  // 50.00%
));

// Fixed amount discount
$discount = LaravelPolar::createDiscount(new Data\DiscountFixedCreate(
    name: '\$10 Off',
    amountInCents: 1000,  // $10.00
));
```

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

### Swap and invoice immediately with swapAndInvoice()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/03-subscription-order-models.md

Swaps to a new product and triggers an immediate invoice without proration.

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

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

### deleteDiscount() usage example

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

Deletes a specific discount record by its ID.

```php
LaravelPolar::deleteDiscount('disc_xxx');
```

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

### activateLicenseKey()

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

Activate a license on a new device. This is a public endpoint.

```APIDOC
## LaravelPolar::activateLicenseKey()

### Description
Activate a license on a new device (public endpoint).

### Parameters
- **key** (string) - Required - License key string
- **label** (string) - Required - Device/machine label
- **organizationId** (string|null) - Optional - Organization ID
- **conditions** (array|null) - Optional - Custom conditions
- **meta** (array|null) - Optional - Metadata to store with activation

### Returns
- **Data\LicenseKeyActivationRead** - Created activation with ID

### Example
```php
$activation = LaravelPolar::activateLicenseKey(key: 'LIC-XXXX-XXXX-XXXX', label: 'Home MacBook Pro');
```
```

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

### 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
)"
```

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

### Page::count() method usage

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Getting the number of items on the current page.

```php
echo count($page); // 50
```

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

### 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
```

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

### HandleSubscriptionRevoked Listener

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

Example listener for the SubscriptionRevoked event to revoke user access.

```php
public function handle(SubscriptionRevoked $event): void
{
    $user = $event->billable;

    // Revoke access
    $user->update(['plan' => 'free']);
}
```

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

### Run tests with Composer

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

Execute the package test suite using the composer test command.

```bash
composer test
```

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

### Retrieve Trial End Date

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

Get the date when the current trial period ends.

```php
$trialEnd = $user->subscription()->trialEndsAt();
```

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

### Get a specific meter with getCustomerMeter()

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

Fetches a single meter object by its unique ID.

```php
public static function getCustomerMeter(string $meterId): Data\CustomerMeter
```

```php
$meter = LaravelPolar::getCustomerMeter('meter_xxx');
echo $meter->displayName;
```

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

### Constructing a Checkout instance

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Instantiate a new Checkout object by passing an array of product IDs.

```php
use Danestves\LaravelPolar\Checkout;

$checkout = new Checkout(['product_123']);
```

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

### Handling BenefitGrantRevoked Event

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

Example of handling the BenefitGrantRevoked event to perform cleanup actions.

```php
public function handle(BenefitGrantRevoked $event): void
{
    $grant = $event->payload->benefitGrant;
    
    // Revoke license key, remove Discord role, etc.
}
```

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

### 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
```

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

### Handling BenefitGrantCreated Event

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

Example of handling the BenefitGrantCreated event by checking the grant type.

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

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

### HandleSubscriptionCanceled Listener

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

Example listener for the SubscriptionCanceled event to notify the user during the grace period.

```php
public function handle(SubscriptionCanceled $event): void
{
    $subscription = $event->subscription;

    // Notify user before access expires
    Mail::to($event->billable->email)->send(
        new SubscriptionCanceledNotification($subscription)
    );
}
```

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

### Publish migrations

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

Manually publish the package migrations.

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

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

### Retrieve and filter orders with orders()

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

Demonstrates how to fetch all orders, filter by paid status, and iterate through the relationship.

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

// Filter paid orders
$paid = $user->orders()->paid()->get();

// Iterate
foreach ($user->orders() as $order) {
    echo $order->amount;
}
```

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

### HandleSubscriptionCreated Listener

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

Example listener for the SubscriptionCreated event to grant access to premium features.

```php
namespace App\Listeners;

use Danestves\LaravelPolar\Events\SubscriptionCreated;

class HandleSubscriptionCreated
{
    public function handle(SubscriptionCreated $event): void
    {
        $user = $event->billable;

        // Grant access to premium features
        $user->update(['plan' => 'premium']);
    }
}
```

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

### 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
```

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

### Swap subscription plans with swap()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/03-subscription-order-models.md

Changes the subscription to a new product. Supports optional proration behavior, defaulting to prorated billing.

```php
// Upgrade plan with proration credit
$subscription->swap('product_premium');

// Or charge immediately for the upgrade
$subscription->swap('product_premium', SubscriptionProrationBehavior::Invoice);
```

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

### Redirect to customer portal with redirectToCustomerPortal()

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

Shows how to use the redirect method in a controller or retrieve the URL directly for redirection.

```php
// In controller
Route::get('/customer-portal', function (Request $request) {
    return $request->user()->redirectToCustomerPortal();
});

// Or get the URL directly
$url = $request->user()->customerPortalUrl();
return redirect($url);
```

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

### Creating and Accessing PolarApiError

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

Example of creating an exception from a failed response and accessing its properties.

```php
// Create exception from a failed response
$error = PolarApiError::fromResponse($response, 'POST', 'https://api.polar.sh/v1/checkouts/');

echo $error->status;  // 400
echo $error->message; // "Polar API error 400 on POST ...: Invalid product_id"
echo $error->body;    // ['detail' => 'Invalid product_id']
```

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

### listCustomerLicenseKeys() method signature

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

The method signature for listing a customer's license keys.

```php
public static function listCustomerLicenseKeys(
    string $customerSessionToken,
    array $query = []
): Page<Data\LicenseKeyRead>
```

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

### List customer meters with listCustomerMeters()

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

Retrieves a collection of all meters associated with the customer.

```php
public function listCustomerMeters(): Collection<CustomerMeter>
```

```php
$meters = $user->listCustomerMeters();

foreach ($meters as $meter) {
    echo $meter->displayName;
}
```

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

### Publish views

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

Manually publish the package views.

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

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

### CustomerStateChanged Event Class

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

Fired when a customer's state changes, for example, from individual to team.

```php
namespace Danestves\LaravelPolar\Events;

class CustomerStateChanged extends WebhookEvent
{
    public readonly array $payload;
}
```

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

### checkout(array|string $products)

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

Creates a checkout session for one or more products, returning a fluent checkout builder.

```APIDOC
## checkout(array|string $products)

### Description
Create a checkout session for one or more products.

### Signature
`public function checkout(array|string $products): Checkout`

### Parameters
- **products** (array|string) - Required - Product ID(s) to checkout

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

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

### Checkout::__construct()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Creates a new instance of the Checkout class with a specified array of product IDs.

```APIDOC
## __construct(array $products)

### Description
Initializes a new checkout instance for the provided product IDs.

### Parameters
- **products** (array) - Required - Array of product IDs to checkout.

### Example
```php
use Danestves\LaravelPolar\Checkout;
$checkout = new Checkout(['product_123']);
```
```

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

### 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
```

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

### Check SeatStatus Usage

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

Example of checking the status of subscription seats using the SeatStatus enum.

```php
use Danestves\LaravelPolar\Enums\SeatStatus;

$seats = $subscription->seats();
foreach ($seats->seats as $seat) {
    if ($seat->status === SeatStatus::Pending) {
        echo "{$seat->email} hasn't accepted invitation yet";
    }
}
```

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

### 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
```

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

### 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
```

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

### Query incomplete expired subscriptions with scopeIncompleteExpired()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/03-subscription-order-models.md

Use this scope to retrieve all subscriptions where the setup has expired.

```php
$expired = Subscription::query()->incompleteExpired()->get();
```

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

### 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
```

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

### Get a specific customer meter

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

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

```php
use Danestves\LaravelPolar\LaravelPolar;

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

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

### Get Customer Portal URL

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

Obtain the signed customer portal URL directly for custom implementation.

```php
$url = $user->customerPortalUrl();
```

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

### updateDiscount() usage example

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

Updates a discount's name using the discount ID and an associative array.

```php
$discount = LaravelPolar::updateDiscount('disc_xxx', [
    'name' => 'Black Friday Extended',
]);
```

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

### withSubscriptionId() method

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Defines the method signature for upgrading an existing free subscription to a paid plan using a subscription ID.

```php
public function withSubscriptionId(string $subscriptionId): self
```

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

### Resume subscription with resume()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/03-subscription-order-models.md

Reactivates a cancelled subscription while it is still within the grace period.

```php
if ($subscription->onGracePeriod()) {
    $subscription->resume(); // Reactivate before grace period ends
}
```

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

### listCustomerLicenseKeys()

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

Retrieves a paginated list of license keys owned by the customer.

```APIDOC
## listCustomerLicenseKeys(string $customerSessionToken, array $query = [])

### Description
List a customer's license keys. Requires a customer session token.

### Parameters
- **customerSessionToken** (string) - Required - Session token
- **query** (array) - Optional - Query filters

### Returns
- **Page<Data\LicenseKeyRead>** - Paginated license keys

### Throws
- **PolarApiError** - On API request failure
```

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

### Clear subscription field

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

Example of using keepNulls: true to explicitly clear a field during a subscription update.

```php
LaravelPolar::updateSubscription('sub_xxx', ['discount_id' => null], keepNulls: true);
```

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

### 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);
```

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

### 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
```

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

### Embedded Checkout Setup

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

Create a checkout link and pass it to the view to use with the embedded blade component.

```php
use Illuminate\Http\Request;

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

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

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

### swapAndInvoice(string $productId)

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/03-subscription-order-models.md

Swaps the subscription to a new product and triggers an immediate invoice without proration.

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

### Description
Swap to a new product and invoice immediately (don't prorate).

### Parameters
- **productId** (string) - Required - New product ID

### Returns
- **self** - Updated subscription (fluent)

### Throws
- **PolarApiError** - On API failure
```

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

### 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
```

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

### Hydrate API responses into typed objects

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

Pass the array returned by the client to a matching data class to get a typed object.

```php
use Danestves\LaravelPolar\Data;

$organization = Data\Organization::from($client->get('/v1/organizations/org_xxx'));
```

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

### Model Configuration Methods

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

Methods to define the FQCN for customer, subscription, and order models.

```APIDOC
## Model Configuration

### useCustomerModel(string $customerModel)
Sets the customer model class name.

### useSubscriptionModel(string $subscriptionModel)
Sets the subscription model class name.

### useOrderModel(string $orderModel)
Sets the order model class name.

### Parameters
- **model** (string) - Required - The Fully Qualified Class Name (FQCN) of the model.

### Example
```php
LaravelPolar::useCustomerModel(\App\Models\User::class);
LaravelPolar::useSubscriptionModel(\App\Models\Subscription::class);
LaravelPolar::useOrderModel(\App\Models\PolarOrder::class);
```
```

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

### Checkout::make()

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

A static factory method to instantiate a new checkout session.

```APIDOC
## static make(array $products)

### Description
Static factory method to create a new checkout instance.

### Parameters
- **products** (array) - Required - Product IDs.

### Returns
- **self** - New checkout instance.

### Example
```php
$checkout = Checkout::make(['product_123', 'product_456']);
```
```

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

### Page::first() method usage

Source: https://github.com/danestves/laravel-polar/blob/main/_autodocs/04-checkout-client.md

Retrieving the first item from a page.

```php
$product = $page->first();
```
Tokens:
Raw