The Billable trait: enable billing on any model

Add the Billable trait to any Eloquent model to unlock checkouts, subscriptions, orders, license keys, usage billing, and the full Polar API.

The Billable trait is the single entry point to everything Laravel Polar does. Add it to any Eloquent model and that model gains the ability to create checkout sessions, manage subscriptions, retrieve orders, work with license keys, track usage events, and more — all through expressive, chainable PHP methods.

Think of Billable like Laravel Cashier’s trait: one line of code turns any model into a full billing entity. Unlike Cashier, it’s not limited to User — add it to Team, Organization, or any other billable entity in your app.

Adding the trait

Import Danestves\LaravelPolar\Billable and add it to your model:

use Danestves\LaravelPolar\Billable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use Billable;
}

The trait can be added to any Eloquent model, not only User. If your application bills teams, organisations, or companies, add Billable to those models instead — or in addition.

use Danestves\LaravelPolar\Billable;
use Illuminate\Database\Eloquent\Model;

class Team extends Model
{
    use Billable;
}

Model requirements

By default the trait reads two attributes from the model when creating customer records and prefilling checkout forms:

Attribute	Used for
name	Customer display name sent to Polar
email	Customer email address sent to Polar

If your model uses different attribute names, or you want to derive these values differently, override either method:

class User extends Authenticatable
{
    use Billable;

    public function polarName(): ?string
    {
        return $this->full_name; // use a different attribute
    }

    public function polarEmail(): ?string
    {
        return $this->billing_email ?? $this->email;
    }
}

What the trait unlocks

The Billable trait is composed of eight focused sub-traits. Here’s a summary of every method each one adds — useful as a quick reference when writing code or asking an AI assistant for help:

Checkouts (ManagesCheckouts)

Method	Description
checkout(array $productIds, string $type = 'default')	Create a checkout session for one or more products
subscribe(string $productId, string $type = 'default')	Create a subscription checkout
charge(int $amount, array $productIds)	Create a checkout with a custom price override

Customer (ManagesCustomer)

Method	Description
redirectToCustomerPortal()	Redirect to the Polar self-service customer portal
customerPortalUrl()	Return the signed customer portal URL as a string

Subscriptions (ManagesSubscription)

Method	Description
subscribed(string $type = 'default')	Check if the model has an active subscription
subscription(string $type = 'default')	Retrieve a Subscription model instance
subscriptions()	Return a query for all subscriptions
subscribedToProduct(string $productId, string $type = 'default')	Check for a valid subscription to a specific product
onTrial(string $type = 'default')	Check if the model is on a trial

Orders (ManagesOrders)

Method	Description
orders()	Eloquent relationship for all orders
hasPurchasedProduct(string $productId)	Check whether a product has been purchased

Payment methods (ManagesPaymentMethods)

Method	Description
paymentMethods()	List saved payment methods
deletePaymentMethod(string $paymentMethodId)	Delete a saved payment method

License keys (ManagesLicenseKeys)

Method	Description
licenseKeys(?string $benefitId = null)	List the customer’s license keys, optionally scoped to a benefit

Benefits (ManagesBenefits)

Method	Description
listBenefits(string $organizationId)	List all benefits for an organisation
getBenefit(string $benefitId)	Retrieve a specific benefit
listBenefitGrants(string $benefitId)	List grants for a specific benefit

Customer meters (ManagesCustomerMeters)

Method	Description
ingestUsageEvent(string $eventName, array $properties, ?int $timestamp = null)	Track a single usage event
ingestUsageEvents(array $events)	Track multiple usage events in a batch
listCustomerMeters()	List all meters for the customer

Customising the underlying models

By default the package uses its own Customer, Subscription, and Order Eloquent models. You can swap in your own — useful when you need to add custom attributes, relationships, or scopes — by calling the appropriate method on the LaravelPolar facade in a service provider’s boot method:

use Danestves\LaravelPolar\LaravelPolar;

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

Your custom models should extend the package’s base models (Danestves\LaravelPolar\Customer, Danestves\LaravelPolar\Subscription, or Danestves\LaravelPolar\Order) so all existing relationships and methods continue to work.

All three use*Model methods are optional. Override only the models you need to customise — the rest will continue using the package defaults.

Next steps

Checkouts

Start creating checkout sessions for one-time payments and subscriptions.

Webhooks

Handle Polar events so your database stays in sync after purchases.