> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subscribd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Status

> Understand subscription states, dates, and status helpers

# 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

| Status       | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| `active`     | Billing is current and the next renewal is scheduled           |
| `trialing`   | In a free trial period; not yet charged                        |
| `paused`     | Billing paused; no charges while paused                        |
| `past_due`   | A payment failed; dunning retries are in progress              |
| `grace`      | Canceled but within the grace period; access still granted     |
| `canceled`   | Canceled by the user or system                                 |
| `expired`    | Ended naturally (e.g. lifetime or one-time plan)               |
| `free`       | Active on a zero-cost plan                                     |
| `lifetime`   | Active on a non-recurring plan                                 |
| `incomplete` | Awaiting gateway confirmation (Paddle webhook-activation flow) |

## Checking status on a subscription

```php theme={null}
$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:

```php theme={null}
$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

```php theme={null}
$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

```php theme={null}
$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`:

```php theme={null}
$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

```php theme={null}
$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:

```blade theme={null}
{{-- Renders a coloured badge for the subscription's current status --}}
<x-subscribd-subscription-badge :subscription="$user->subscription()" />
```

For custom display:

```blade theme={null}
@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:

```blade theme={null}
<livewire:subscribd::subscriber.subscription-manager />
```

See [Livewire Components](/components/livewire) for the full component reference.

## Next steps

* **[Trials](/subscriptions/trials)** — Convert, cancel, or extend a trial
* **[Swapping Plans](/subscriptions/swapping)** — Change plans mid-cycle
* **[Canceling](/subscriptions/canceling)** — Cancel immediately or at period end