Trial Management

Trials give users time to evaluate your product before they’re charged. Subscribd handles the full trial lifecycle — from starting a no-card trial to converting it to a paid subscription.

Starting a trial

Trials start automatically when a plan defines trial_days. No extra code is needed in the subscription creation call:

// config/subscribd.php
'plans' => [
    'pro' => [
        'trial_days' => 14,
        // ...
    ],
],

use Pixelworxio\Subscribd\Actions\CreateSubscription;
use Pixelworxio\Subscribd\Models\Plan;

$plan = Plan::where('key', 'pro')->firstOrFail();
app(CreateSubscription::class)->execute($user, $plan);

$subscription = $user->subscription();
$subscription->onTrial();       // true
$subscription->trial_ends_at;   // CarbonImmutable 14 days from now

Card-free trials

Set trial_requires_payment_method to false on the plan to start a trial without collecting payment details:

'pro' => [
    'trial_days'                    => 14,
    'trial_requires_payment_method' => false,
    // ...
],

With this setting, CreateSubscription makes no gateway API call. The subscription’s gateway_id is null until the trial is converted to active via ConvertTrialToActive, at which point the gateway creates the subscription and collects payment.

Converting a trial to active

Use ConvertTrialToActive to end the trial immediately and collect payment:

use Pixelworxio\Subscribd\Actions\ConvertTrialToActive;

$subscription = $user->subscription();
app(ConvertTrialToActive::class)->execute($subscription);

What happens:

The gateway creates or updates the subscription and triggers the first charge.
On payment success, the subscription transitions to Active and TrialEnded is fired with $converted = true.
On payment failure, the subscription transitions to PastDue and TrialEnded is fired with $converted = false. Dunning retries begin.

Extending a trial

Add days to a trial, or set an explicit end date:

use Pixelworxio\Subscribd\Actions\ExtendTrial;
use Carbon\CarbonImmutable;

// Add 14 days to the trial
app(ExtendTrial::class)->execute($subscription, days: 14);

// Set an explicit trial end date
app(ExtendTrial::class)->execute($subscription, until: CarbonImmutable::parse('2026-09-01'));

When the active gateway supports trial extension, the new date is pushed to the gateway. Otherwise, only the local trial_ends_at column is updated. Gateway support for trial extension:

Gateway	Supported
Stripe	✅ Yes
PayPal	❌ No
Braintree	❌ No
Paddle	❌ No
FastSpring	❌ No
Square	❌ No

Canceling a trial

Cancel a Trialing subscription before it converts:

use Pixelworxio\Subscribd\Actions\CancelTrial;

app(CancelTrial::class)->execute($subscription);

This delegates to CancelSubscription with immediately: true. Throws SubscriptionException if the subscription is not in Trialing status.

Trial helpers on the billable

// Extend the default subscription's trial by 7 days
$user->extendTrial(days: 7);
$user->extendTrial('team', days: 7);           // named slot

// Cancel the trial
$user->cancelTrial();
$user->cancelTrial('team');

// Convert the trial to active (triggers payment)
$user->convertTrial();
$user->convertTrial('team');

These helpers delegate to the corresponding action classes.

Listening to trial events

use Pixelworxio\Subscribd\Events\TrialEnded;

Event::listen(TrialEnded::class, function (TrialEnded $event): void {
    if ($event->converted) {
        // Payment succeeded — subscription is now Active
    } else {
        // Payment failed — subscription is now PastDue
    }
});

Other trial-related events dispatched by the package:

Event	Fired when
`TrialEnded`	Trial converts or payment fails at conversion
`SubscriptionUpdated`	Trial extended
`SubscriptionCanceled`	Trial canceled

The TrialStatus Livewire component

Drop the trial-status component into any Livewire view to give subscribers a self-service trial management UI:

<livewire:subscribd::subscriber.trial-status />

{{-- Named subscription slot --}}
<livewire:subscribd::subscriber.trial-status :subscription-name="'team'" />

The component shows:

Days remaining in the trial
A “Convert to paid” button (triggers ConvertTrialToActive)
An “Extend trial” button when the gateway supports it (Stripe)
A “Cancel trial” button with inline confirmation

It is automatically composed into subscription-manager when the subscription is on trial — no extra wiring needed.

Blade static component

A read-only variant with no action buttons:

<x-subscribd-trial-status />
<x-subscribd-trial-status subscription-name="team" />

Renders nothing when the user is not on a trial.

Scheduled trial expiry

Add the following scheduled command to expire trials automatically. Subscribd runs this via subscribe:expire-trials:

// routes/console.php
Schedule::command('subscribd:expire-trials')->hourly();
Schedule::command('subscribd:dispatch-trial-ending-events')->daily();

dispatch-trial-ending-events fires TrialEnding for each trial that ends within the next 72 hours, giving you time to send reminder emails.

Next steps

Subscription Status — Full status reference
Hooks and Events — All billing events
Livewire Components — TrialStatus component reference

Getting Started

Billing Scenarios

Subscriptions

Gateways

Entitlements

Invoices & Charges

Coupons

Components

Advanced

Trial Management

Trial Management

Starting a trial

Card-free trials

Converting a trial to active

Extending a trial

Canceling a trial

Trial helpers on the billable

Listening to trial events

The TrialStatus Livewire component

Blade static component

Scheduled trial expiry

Next steps

​Trial Management

​Starting a trial

​Card-free trials

​Converting a trial to active

​Extending a trial

​Canceling a trial

​Trial helpers on the billable

​Listening to trial events

​The TrialStatus Livewire component

​Blade static component

​Scheduled trial expiry

​Next steps

Trial Management

Starting a trial

Card-free trials

Converting a trial to active

Extending a trial

Canceling a trial

Trial helpers on the billable

Listening to trial events

The TrialStatus Livewire component

Blade static component

Scheduled trial expiry

Next steps