LaravelPolar facade: complete API reference

Every method on the LaravelPolar facade, grouped by category — with signatures, parameter types, and return types drawn from the source.

The LaravelPolar facade is the primary entry point for calling Polar’s API from anywhere in your application. Every method is a thin, opinionated wrapper that:

• Authenticates the request with your configured POLAR_ACCESS_TOKEN
• Calls the underlying Polar PHP SDK
• Throws a typed Polar\Models\Errors\APIException if the request fails

All methods are static and can be called from controllers, jobs, services, or anywhere else.

All Components\* and Operations\* types referenced below live in the Polar\Models\Components and Polar\Models\Operations namespaces respectively. Import them with use Polar\Models\Components; and use Polar\Models\Operations;.

---

Checkouts

createCheckoutSession

Create a hosted checkout session and redirect the customer to Polar’s checkout page.

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

$checkout = LaravelPolar::createCheckoutSession(
    new Components\CheckoutCreate(
        productPriceId: 'price_xxx',
    )
);

return redirect($checkout->url);

Parameter	Type	Description
$request	Components\CheckoutCreate	Checkout creation payload.

Returns Components\Checkout — the created checkout object, including its hosted url.

Throws Errors\APIException when the API returns a non-201 status.

---

Checkout links

Checkout links are reusable, shareable URLs that do not require a live session. Use them in marketing emails, landing pages, or “Buy now” buttons.

createCheckoutLink

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

echo $link->url;

Three create variants are available:

Class	When to use
CheckoutLinkCreateProduct	Single product, any price
CheckoutLinkCreateProductPrice	Single product pinned to a specific price
CheckoutLinkCreateProducts	Multiple products — customer picks one

Returns Components\CheckoutLink.

updateCheckoutLink

LaravelPolar::updateCheckoutLink(
    'cl_xxx',
    new Components\CheckoutLinkUpdate(label: 'Black Friday')
);

Parameter	Type	Description
$checkoutLinkId	string	ID of the checkout link to update.
$request	Components\CheckoutLinkUpdate	Fields to update.

Returns Components\CheckoutLink.

deleteCheckoutLink

LaravelPolar::deleteCheckoutLink('cl_xxx');

Parameter	Type	Description
$checkoutLinkId	string	ID of the checkout link to delete.

Returns void. Throws on non-200/204 status.

listCheckoutLinks

$response = LaravelPolar::listCheckoutLinks();
// or with filters:
$response = LaravelPolar::listCheckoutLinks(
    new Operations\CheckoutLinksListRequest(page: 1, limit: 20)
);

Parameter	Type	Description
$request	?Operations\CheckoutLinksListRequest	Optional filters and pagination. Defaults to a blank request.

Returns Operations\CheckoutLinksListResponse.

getCheckoutLink

$link = LaravelPolar::getCheckoutLink('cl_xxx');

Parameter	Type	Description
$checkoutLinkId	string	ID of the checkout link to fetch.

Returns Components\CheckoutLink.

---

Subscriptions

updateSubscription

Modify an existing subscription — swap product, cancel, apply or remove a discount, adjust the trial, update seats, or revoke.

use Polar\Models\Components;

// Swap to a different product:
LaravelPolar::updateSubscription(
    'sub_xxx',
    new Components\SubscriptionUpdateProduct(productId: 'product_yyy')
);

// Cancel at period end:
LaravelPolar::updateSubscription(
    'sub_xxx',
    new Components\SubscriptionCancel()
);

Parameter	Type	Description
$subscriptionId	string	ID of the subscription to update.
$request	`SubscriptionUpdateProduct	SubscriptionCancel	SubscriptionUpdateDiscount	SubscriptionUpdateTrial	SubscriptionUpdateSeats	SubscriptionRevoke`	The specific update variant to apply.

Returns Components\Subscription.

For most use cases you should prefer the fluent helpers on the Subscription model ($subscription->swap(), $subscription->cancel(), $subscription->applyDiscount()) — they call this method under the hood.

---

Products

listProducts

Retrieve all products available in your Polar organization.

$response = LaravelPolar::listProducts();

foreach ($response->listResourceProduct?->items ?? [] as $product) {
    echo $product->name;
}

You can filter with a request object:

$response = LaravelPolar::listProducts(
    new Operations\ProductsListRequest(isArchived: false)
);

Parameter	Type	Description
$request	?Operations\ProductsListRequest	Optional filters. Defaults to a blank request when null.

Returns Operations\ProductsListResponse.

---

Customers

createCustomerSession

Mint a short-lived customer session token. The package uses this internally to authenticate customer-portal and payment-method calls without exposing your admin token.

$session = LaravelPolar::createCustomerSession(
    new Components\CustomerSessionCustomerIDCreate(customerId: 'cust_xxx')
);

// or by external ID:
$session = LaravelPolar::createCustomerSession(
    new Components\CustomerSessionCustomerExternalIDCreate(externalCustomerId: 'user_42')
);

Parameter	Type	Description
$request	`CustomerSessionCustomerIDCreate	CustomerSessionCustomerExternalIDCreate`	Identifies the customer either by Polar ID or your own external ID.

Returns Components\CustomerSession.

---

Discounts

Discounts are reusable coupon codes. Four create variants cover fixed/percentage amounts and once/repeat durations.

createDiscount

$discount = LaravelPolar::createDiscount(
    new Components\DiscountPercentageOnceForeverDurationCreate(
        name: 'Black Friday 50%',
        type: Components\DiscountType::Percentage,
        duration: Components\DiscountDuration::Once,
        basisPoints: 5000,
        organizationId: 'your-org-id',
    )
);

Parameter	Type
$request	`DiscountFixedOnceForeverDurationCreate	DiscountFixedRepeatDurationCreate	DiscountPercentageOnceForeverDurationCreate	DiscountPercentageRepeatDurationCreate`

Returns the matching discount response union type.

updateDiscount

LaravelPolar::updateDiscount(
    'disc_xxx',
    new Components\DiscountUpdate(name: 'Black Friday extended')
);

Parameter	Type
$discountId	string
$request	Components\DiscountUpdate

Returns discount union type.

deleteDiscount

LaravelPolar::deleteDiscount('disc_xxx');

Returns void.

listDiscounts

$response = LaravelPolar::listDiscounts();
// or filtered:
$response = LaravelPolar::listDiscounts(new Operations\DiscountsListRequest());

Parameter	Type
$request	?Operations\DiscountsListRequest

Returns Operations\DiscountsListResponse.

getDiscount

$discount = LaravelPolar::getDiscount('disc_xxx');

Returns discount union type.

---

Benefits

Benefits are features automatically granted to customers when they buy a product. Six create variants are supported: BenefitCustomCreate, BenefitDiscordCreate, BenefitGitHubRepositoryCreate, BenefitDownloadablesCreate, BenefitLicenseKeysCreate, BenefitMeterCreditCreate.

createBenefit

$benefit = LaravelPolar::createBenefit(
    new Components\BenefitCustomCreate(
        description: 'Premium Support',
        organizationId: 'your-org-id',
        properties: new Components\BenefitCustomCreateProperties(),
    )
);

Returns benefit union type.

updateBenefit

LaravelPolar::updateBenefit(
    'benefit_xxx',
    new Components\BenefitCustomUpdate(description: 'Updated Premium Support')
);

Parameter	Type
$benefitId	string
$request	benefit update union type

Returns benefit union type.

deleteBenefit

LaravelPolar::deleteBenefit('benefit_xxx');

Returns void.

listBenefits

$response = LaravelPolar::listBenefits(
    new Operations\BenefitsListRequest()
);

Parameter	Type
$request	Operations\BenefitsListRequest

Returns Operations\BenefitsListResponse.

getBenefit

$benefit = LaravelPolar::getBenefit('benefit_xxx');

Returns benefit union type.

listBenefitGrants

List all grants for a specific benefit — i.e. which customers have been given it.

$response = LaravelPolar::listBenefitGrants(
    new Operations\BenefitsGrantsRequest(benefitId: 'benefit_xxx')
);

Parameter	Type
$request	Operations\BenefitsGrantsRequest

Returns Operations\BenefitsGrantsResponse.

---

Custom fields

Custom fields let you collect arbitrary data at checkout — company name, VAT number, seat count, and so on. Five field types are supported: Text, Number, Date, Checkbox, Select.

createCustomField

$field = LaravelPolar::createCustomField(
    new Components\CustomFieldCreateText(
        slug: 'company',
        name: 'Company name',
        properties: new Components\CustomFieldTextProperties(),
    )
);

Parameter	Type
$request	`CustomFieldCreateText	CustomFieldCreateNumber	CustomFieldCreateDate	CustomFieldCreateCheckbox	CustomFieldCreateSelect`

Returns custom field union type.

updateCustomField

LaravelPolar::updateCustomField(
    'cf_xxx',
    new Components\CustomFieldUpdateText(name: 'Organization name')
);

Parameter	Type
$customFieldId	string
$request	custom field update union type

Returns custom field union type.

deleteCustomField

LaravelPolar::deleteCustomField('cf_xxx');

Returns void.

listCustomFields

$response = LaravelPolar::listCustomFields();
// or with filters:
$response = LaravelPolar::listCustomFields(
    new Operations\CustomFieldsListRequest()
);

Parameter	Type
$request	?Operations\CustomFieldsListRequest

Returns Operations\CustomFieldsListResponse.

getCustomField

$field = LaravelPolar::getCustomField('cf_xxx');

Returns custom field union type.

---

License keys

License keys are a benefit type for desktop apps, CLIs, and SDKs. The facade exposes three distinct surfaces: admin management (org-scoped token), public verification (no admin token required), and listing keys per customer.

The public verification methods (validateLicenseKey, activateLicenseKey, deactivateLicenseKey) require an organization ID. Either pass it explicitly on each call, or set POLAR_ORGANIZATION_ID in your .env and the package resolves it automatically.

listLicenseKeys

Admin-scoped. Lists all license keys for your organization.

$response = LaravelPolar::listLicenseKeys();

// Filter by benefit or scope to a specific organization:
$response = LaravelPolar::listLicenseKeys(
    organizationId: 'org_xxx',
    benefitId: 'benefit_xxx',
    page: 1,
    limit: 50,
);

Parameter	Type	Default
$organizationId	`string	array	null`	null
$benefitId	`string	array	null`	null
$page	?int	null
$limit	?int	null

Returns Operations\LicenseKeysListResponse.

getLicenseKey

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

echo $key->activations; // array of LicenseKeyActivationRead

Returns Components\LicenseKeyWithActivations.

updateLicenseKey

LaravelPolar::updateLicenseKey(
    'lk_xxx',
    new Components\LicenseKeyUpdate(limitActivations: 10)
);

Parameter	Type
$licenseKeyId	string
$request	Components\LicenseKeyUpdate

Returns Components\LicenseKeyRead.

validateLicenseKey

Public-facing. Validates a key and optionally increments a usage counter.

$validated = LaravelPolar::validateLicenseKey(
    key: 'LIC-XXXX-XXXX-XXXX',
    activationId: 'act_xxx',     // optional — bind to a specific activation
    incrementUsage: 1,           // optional — metered usage
);

Parameter	Type	Default
$key	string	—
$organizationId	?string	reads polar.organization_id config
$activationId	?string	null
$conditions	?array<string, mixed>	null
$benefitId	?string	null
$customerId	?string	null
$incrementUsage	?int	null

Returns Components\ValidatedLicenseKey.

activateLicenseKey

Register a new device/activation for a key.

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

Parameter	Type	Default
$key	string	—
$label	string	—
$organizationId	?string	reads config
$conditions	?array<string, mixed>	null
$meta	?array<string, mixed>	null

Returns Components\LicenseKeyActivationRead.

deactivateLicenseKey

Remove a specific activation from a key.

LaravelPolar::deactivateLicenseKey(
    key: 'LIC-XXXX-XXXX-XXXX',
    activationId: 'act_xxx',
);

Parameter	Type	Default
$key	string	—
$activationId	string	—
$organizationId	?string	reads config

Returns void.

---

Refunds

createRefund

Issue a refund for an order.

LaravelPolar::createRefund(
    new Components\RefundCreate(
        orderId: 'ord_xxx',
        reason: Components\RefundReason::Duplicate,
        amount: 1000, // minor units (cents)
    )
);

Returns Components\Refund.

For refunding from an Order model instance, use the Cashier-style $order->refund() helper instead.

listRefunds

$response = LaravelPolar::listRefunds(
    new Operations\RefundsListRequest(orderId: 'ord_xxx')
);

Parameter	Type
$request	?Operations\RefundsListRequest

Returns Operations\RefundsListResponse.

---

Team seats

Seat management for multi-user subscriptions. The facade methods operate cross-subscription; for subscription-scoped helpers see the Subscription model.

listSeats

$seatsList = LaravelPolar::listSeats(subscriptionId: 'sub_xxx');

$seatsList->seats;          // array<Components\CustomerSeat>
$seatsList->availableSeats; // int
$seatsList->totalSeats;     // int

Parameter	Type	Default
$subscriptionId	?string	null
$orderId	?string	null

Returns Components\SeatsList.

assignSeat

Assign a seat by email (sends an invitation) or by customer/external ID (assigns directly).

LaravelPolar::assignSeat(
    new Components\SeatAssign(
        subscriptionId: 'sub_xxx',
        email: '[e-mail]',
    )
);

Returns Components\CustomerSeat.

revokeSeat

LaravelPolar::revokeSeat('seat_xxx');

Returns Components\CustomerSeat.

resendSeatInvitation

Resend the invitation email for a pending seat.

LaravelPolar::resendSeatInvitation('seat_xxx');

Returns Components\CustomerSeat.

---

Usage / events

Track metered usage for usage-based billing.

ingestEvents

Send one or more usage events in a single batch.

LaravelPolar::ingestEvents(
    new Components\EventsIngest(
        events: [
            new Components\Event(
                name: 'api_request',
                externalCustomerId: 'user_42',
                metadata: ['endpoint' => '/v1/data'],
            ),
        ]
    )
);

Returns void. Throws if Polar returns a non-202 response.

For a Cashier-style helper that automatically attaches the current customer, use $user->ingestUsageEvent() or $user->ingestUsageEvents() on your billable model.

listCustomerMeters

$response = LaravelPolar::listCustomerMeters(
    new Operations\CustomerMetersListRequest(externalCustomerId: 'user_42')
);

Parameter	Type
$request	Operations\CustomerMetersListRequest

Returns Operations\CustomerMetersListResponse.

getCustomerMeter

$meter = LaravelPolar::getCustomerMeter('meter_xxx');

Returns Components\CustomerMeter.

---

Analytics

getMetrics

Fetch aggregated revenue and usage metrics for a date range.

use Brick\DateTime\LocalDate;
use Polar\Models\Components;
use Polar\Models\Operations;

$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->startDatetime . ': ' . $period->revenue;
}

Parameter	Type
$request	Operations\MetricsGetRequest

Returns Components\MetricsResponse.

---

Files & organizations

listFiles

List downloadable assets, product media, and organization avatars.

$response = LaravelPolar::listFiles();

// Filter by organization or specific IDs:
$response = LaravelPolar::listFiles(
    organizationId: 'org_xxx',
    ids: ['file_aaa', 'file_bbb'],
    page: 1,
    limit: 20,
);

$items = $response->listResourceFileRead?->items ?? [];

Parameter	Type	Default
$organizationId	`string	array	null`	null
$ids	`string	array	null`	null
$page	?int	null
$limit	?int	null

Returns Operations\FilesListResponse.

listOrganizations

$response = LaravelPolar::listOrganizations(slug: 'my-org');

Parameter	Type	Default
$slug	?string	null
$page	?int	null
$limit	?int	null

Returns Operations\OrganizationsListResponse.

getOrganization

$org = LaravelPolar::getOrganization('org_xxx');

Returns Components\Organization.

---

Model customization

Override the Eloquent models the package resolves for customers, subscriptions, and orders. Call these methods in the boot method of a service provider.

useCustomerModel

use App\Models\PolarCustomer;
use Danestves\LaravelPolar\LaravelPolar;

LaravelPolar::useCustomerModel(PolarCustomer::class);

useSubscriptionModel

LaravelPolar::useSubscriptionModel(App\Models\PolarSubscription::class);

useOrderModel

LaravelPolar::useOrderModel(App\Models\PolarOrder::class);

All three methods accept a fully qualified class name string and return void. The custom class must extend the corresponding base model (Danestves\LaravelPolar\Customer, Subscription, or Order).

---

SDK access

sdk

Returns the underlying Polar\Polar SDK client. Use this to reach any Polar endpoint that the facade does not wrap directly.

$sdk = LaravelPolar::sdk();

Returns Polar\Polar — the underlying SDK client, built from your polar.access_token and polar.server config values. Throws Exception if the access token is not set.

See Access the Polar SDK directly for examples of what you can do with the raw client.