Usage-based billing with metered events

Charge customers based on actual consumption by ingesting usage events into Polar, then query meter balances through the Billable trait and facade.

Usage-based billing lets you charge customers based on actual consumption rather than a flat fee. Emit named events from your application — for example api_request or storage_used — and Polar aggregates them against a meter definition. At the end of the billing period, Polar calculates the charge automatically.

Events are not stored locally. They are forwarded to Polar for processing. Use the Polar dashboard or the meters API to view aggregated usage data. Define meters and attach them to products in the Polar dashboard first.

Tracking a single event

Call ingestUsageEvent() on your billable model. Pass the event name and an optional array of properties that describe the event:

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

The method silently no-ops if the user does not yet have an associated Polar customer record, so it is safe to call unconditionally in middleware or service classes without wrapping in a try/catch.

Batch ingestion

When you need to record multiple events at once — for example at the end of a background job — use ingestUsageEvents() to send them all in a single API call:

$user->ingestUsageEvents([
    [
        'eventName' => 'api_request',
        'properties' => [
            'endpoint' => '/api/v1/data',
            'method' => 'GET',
        ],
    ],
    [
        'eventName' => 'storage_used',
        'properties' => [
            'bytes' => 1048576,
        ],
        'timestamp' => new \DateTime(), // optional; defaults to now
    ],
]);

Event structure

Each item in the array supports the following keys:

Key	Type	Required	Description
eventName	string	Yes	The name of the meter event to record
properties	array	No	Arbitrary key/value metadata for the event
timestamp	\DateTime	No	Event timestamp; defaults to the current time

Events are sent directly to Polar for processing. They are not persisted in your local database. Use the Polar dashboard or the meters API to view aggregated usage data.

Listing customer meters

Retrieve all meters for a customer to inspect their current balances:

$response = $user->listCustomerMeters();
// Returns Operations\CustomerMetersListResponse

The response object contains pagination metadata and an items array of Components\CustomerMeter objects.

Getting a specific meter

Use the LaravelPolar facade when you know the meter ID and want to fetch it directly:

use Danestves\LaravelPolar\LaravelPolar;

$meter = LaravelPolar::getCustomerMeter('meter-id-123');
// Returns Components\CustomerMeter

To associate a meter with a specific customer when calling listCustomerMeters() directly via the facade, pass a Operations\CustomerMetersListRequest with the customerId set. The $user->listCustomerMeters() method handles this automatically.