Subscription trials with Laravel Polar

Check trial status, read the trial end date, detect expired trials, and update the trial period directly from your subscription model.

Polar supports free trial periods on subscriptions. Trial data is synced automatically whenever a subscription is created or updated via webhooks — you don’t need to manage trial state manually. Laravel Polar stores the trial end date in a trial_ends_at column and exposes a set of methods to read and update it.

Where to configure trials: Define the trial period on your product in the Polar dashboard. The package picks it up automatically from the webhook — there’s nothing to configure in Laravel.

How trials work

When Polar creates a subscription with a trial period, it includes the trial end date in the webhook payload. Laravel Polar stores this automatically and keeps it up to date whenever SubscriptionCreated or SubscriptionUpdated webhooks arrive.

You don’t need to configure trials in Laravel Polar — define the trial period on your product in the Polar dashboard, and the package keeps trial_ends_at in sync automatically.

Checking if a subscription is on trial

Call onTrial() on a subscription instance to check whether it is currently in the trialing state:

if ($user->subscription()->onTrial()) {
    // Subscription is active and within the trial period
}

onTrial() returns false once the trial ends and the subscription transitions to active status.

You can also check trial status directly on the billable model without loading the subscription first:

if ($user->onTrial()) {
    // The default subscription is currently on trial
}

// Check a named subscription type
if ($user->onTrial('swimming')) {
    // The swimming subscription is on trial
}

Reading the trial end date

trialEndsAt() returns the trial end timestamp as a Carbon instance, or null if no trial is set:

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

if ($trialEnd) {
    echo 'Trial ends on ' . $trialEnd->toFormattedDateString();
}

Display the trial end date in your UI to remind customers how much free time they have left before their first charge.

Detecting an expired trial

hasExpiredTrial() returns true when a trial end date is recorded and that date is in the past. This is useful for showing a prompt after the trial ends but before the customer actively cancels:

if ($user->subscription()->hasExpiredTrial()) {
    // Trial has ended — consider prompting for a payment method upgrade
}

Note that an expired trial does not mean the subscription itself is invalid. If the customer has a payment method on file, Polar transitions the subscription from trialing to active automatically.

Updating the trial period

You can extend or shorten the trial period programmatically by calling updateTrial() with any DateTimeInterface:

$user->subscription()->updateTrial(now()->addDays(30));

This calls the Polar API and syncs the updated trial end date back to your local database.

updateTrial() modifies the trial end date on Polar’s side. Use it carefully — setting a date in the past will immediately end the trial and may trigger a billing event depending on your Polar product configuration.