Automate product benefits with Polar

Define automated features that Polar grants when customers purchase your products, and react to grant lifecycle events using typed Laravel webhook events.

Benefits are automated features that Polar grants to customers when they purchase a product. Instead of writing custom webhook logic for every perk you offer, you define benefits once in Polar and let the platform handle delivery.

The LaravelPolar facade covers the full lifecycle: create, update, delete, list, and fetch. Your Billable model also exposes helpers for listing benefits and their grants per customer.

Benefits vs. features: A “benefit” is a Polar concept — it’s the mechanism that delivers a feature (like a Discord role or a license key) to a customer after purchase. You react to benefit grant/revoke events with Laravel listeners.

Benefit types

Polar supports six built-in benefit types:

Type	Class	Description
Custom	BenefitCustomCreate	Any ad-hoc benefit you describe in text
Discord	BenefitDiscordCreate	Automatic Discord role assignment
GitHub Repository	BenefitGitHubRepositoryCreate	Grant access to a private GitHub repository
Downloadables	BenefitDownloadablesCreate	Files customers can download after purchase
License Keys	BenefitLicenseKeysCreate	Issue license keys on purchase
Meter Credit	BenefitMeterCreditCreate	Award usage-meter credits on purchase

Creating a benefit

Pass one of the six create classes to LaravelPolar::createBenefit(). The example below creates a custom benefit, but the same pattern applies to all types.

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

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

For other benefit types, swap the class and properties object:

// GitHub Repository access
LaravelPolar::createBenefit(new Components\BenefitGitHubRepositoryCreate(/* ... */));

// Discord role
LaravelPolar::createBenefit(new Components\BenefitDiscordCreate(/* ... */));

// License keys
LaravelPolar::createBenefit(new Components\BenefitLicenseKeysCreate(/* ... */));

Updating a benefit

$benefit = LaravelPolar::updateBenefit(
    'benefit-id-123',
    new Components\BenefitCustomUpdate(
        description: 'Updated Premium Support',
        properties: new Components\BenefitCustomUpdateProperties(),
    )
);

Each benefit type has a corresponding *Update class — e.g. BenefitDiscordUpdate, BenefitGitHubRepositoryUpdate, and so on.

Deleting a benefit

LaravelPolar::deleteBenefit('benefit-id-123');

Deleting a benefit removes it from all products it is attached to. Any customers who were granted the benefit will have their grants revoked and a BenefitGrantRevoked event will be dispatched.

Listing and fetching benefits

use Polar\Models\Operations;

// List benefits for an organization
$response = LaravelPolar::listBenefits(
    new Operations\BenefitsListRequest(organizationId: 'your-org-id')
);

// Fetch a single benefit
$benefit = LaravelPolar::getBenefit('benefit-id-123');

Billable model helpers

The Billable trait adds three convenience methods to your model:

// List all benefits for an organization
$benefits = $user->listBenefits('your-org-id');

// Fetch a single benefit by ID
$benefit = $user->getBenefit('benefit-id-123');

// List all grants for a specific benefit
$grants = $user->listBenefitGrants('benefit-id-123');

listBenefits() and listBenefitGrants() return the full Operations\BenefitsListResponse and Operations\BenefitsGrantsResponse respectively, giving you access to pagination metadata alongside the items.

Webhook events

Laravel Polar dispatches three typed events when a benefit grant changes state. Register listeners for them in your EventServiceProvider (or let Laravel’s auto-discovery find them):

Event	Triggered when
BenefitGrantCreated	A benefit is granted after a successful purchase
BenefitGrantUpdated	An existing grant is modified
BenefitGrantRevoked	A grant is removed (e.g. subscription cancelled)

All three events expose a $billable convenience property pointing to the associated billable model, plus a $payload containing the full webhook payload.

use Danestves\LaravelPolar\Events\BenefitGrantCreated;
use Danestves\LaravelPolar\Events\BenefitGrantRevoked;

class HandleBenefitGrants
{
    public function handleGrantCreated(BenefitGrantCreated $event): void
    {
        $user = $event->billable; // your billable model

        // Provision whatever the benefit requires
    }

    public function handleGrantRevoked(BenefitGrantRevoked $event): void
    {
        $user = $event->billable;

        // Revoke access
    }
}

Configure your Polar webhook to send benefit_grant.created, benefit_grant.updated, and benefit_grant.revoked events so that these listeners fire reliably.