Skip to main content

​
Subscription Status

Every subscription has a status that reflects its current position in the billing lifecycle. Subscribd provides helper methods on both the Subscription model and the ManagesBilling trait so you can query state concisely from anywhere in your application.

​
Status values

StatusDescription
activeBilling is current and the next renewal is scheduled
trialingIn a free trial period; not yet charged
pausedBilling paused; no charges while paused
past_dueA payment failed; dunning retries are in progress
graceCanceled but within the grace period; access still granted
canceledCanceled by the user or system
expiredEnded naturally (e.g. lifetime or one-time plan)
freeActive on a zero-cost plan
lifetimeActive on a non-recurring plan
incompleteAwaiting gateway confirmation (Paddle webhook-activation flow)

​
Checking status on a subscription

$subscription = $user->subscription(); // default slot

$subscription->status;              // SubscriptionStatus enum instance
$subscription->status->value;       // string: 'active', 'trialing', etc.

$subscription->onTrial();           // true when status = trialing
$subscription->onGracePeriod();     // true when status = grace

​
Checking status on the billable

The ManagesBilling trait exposes convenience methods that query the default subscription slot: 
$user->subscribed();                // has an active or trialing subscription named 'default'
$user->subscribed('team');          // named slot
$user->onTrial();                   // 'default' slot is trialing
$user->onTrial('team');             // named slot
$user->onGracePeriod();             // 'default' slot is in grace period
$user->onGracePeriod('team');       // named slot

​
Important dates

$subscription = $user->subscription();

$subscription->trial_ends_at;       // CarbonImmutable|null — when the trial ends
$subscription->renews_at;           // CarbonImmutable|null — next renewal date
$subscription->paused_at;           // CarbonImmutable|null — when the pause started
$subscription->paused_until;        // CarbonImmutable|null — scheduled auto-resume date
$subscription->canceled_at;         // CarbonImmutable|null — when cancellation was requested
$subscription->ends_at;             // CarbonImmutable|null — when access ends (grace period end)

​
Plan and price information

$subscription->plan;                // Plan model
$subscription->plan->key;           // 'pro'
$subscription->plan->name;          // 'Professional'
$subscription->plan->amount;        // 4900 (minor units)
$subscription->plan->interval;      // 'month'
$subscription->plan->features;      // array of feature keys/limits
$subscription->currency;            // 'USD' — stored per-subscription
$subscription->currentPrice();      // Money value object for the current effective price

​
Subscription items

Each PlanItem on the plan creates a corresponding SubscriptionItem: 
$subscription->items;                       // HasMany collection of SubscriptionItem models

foreach ($subscription->items as $item) {
    $item->plan_item_key;                   // 'extra_projects'
    $item->quantity;                        // current quantity
    $item->price_override;                  // int|null — custom price in minor units
    $item->isPriceOverrideExpired();        // bool
    $item->hasPriceOverride();              // bool
}

​
Invoice access

$subscription->invoices();           // HasMany
$subscription->latestInvoice();      // most recent Invoice model or null

​
Displaying status in Blade

Subscribd ships a <x-subscribd-subscription-badge> Blade component that renders the appropriate badge automatically: 
{{-- Renders a coloured badge for the subscription's current status --}}
<x-subscribd-subscription-badge :subscription="$user->subscription()" />
For custom display: 
@php $subscription = $user->subscription(); @endphp

@if ($subscription?->onTrial())
    Trial ends {{ $subscription->trial_ends_at->diffForHumans() }}
@elseif ($subscription?->status->value === 'active')
    Renews {{ $subscription->renews_at->format('F j, Y') }}
@elseif ($subscription?->onGracePeriod())
    Access ends {{ $subscription->ends_at->format('F j, Y') }}
@elseif ($subscription?->status->value === 'past_due')
    Payment failed — please update your payment method
@else
    Not subscribed. <a href="{{ route('billing') }}">Choose a plan</a>
@endif

​
Livewire components

The subscription-manager Livewire component renders the full subscription status card with actions automatically: 
<livewire:subscribd::subscriber.subscription-manager />
See Livewire Components for the full component reference.

​
Next steps