> ## 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.

# Canceling Subscriptions

> Cancel subscriptions immediately or at the end of the billing period

# Canceling Subscriptions

The `CancelSubscription` action cancels a subscription at the gateway and updates the local record. All cancellation logic runs inside a database transaction and fires `SubscriptionCanceled` on success.

## Cancel at period end (default)

The default cancel policy leaves the subscription active until the current billing period ends:

```php theme={null}
use Pixelworxio\Subscribd\Actions\CancelSubscription;

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

The subscription enters `Grace` status. The user retains full access until `ends_at`, after which the subscription transitions to `Canceled`. The number of grace period days is configured globally:

```php theme={null}
// config/subscribd.php
'grace_period_days' => env('SUBSCRIBD_GRACE_PERIOD_DAYS', 3),
```

## Cancel immediately

Pass `true` as the second argument to cancel without a grace period:

```php theme={null}
app(CancelSubscription::class)->execute($subscription, immediately: true);
```

The subscription transitions directly to `Canceled`. The user loses access immediately.

## Per-plan cancel policy

Set a `cancel_policy` on individual plans to override the global default:

```php theme={null}
// config/subscribd.php
'plans' => [
    'lifetime' => [
        'cancel_policy' => 'immediately',
        // ...
    ],
    'pro' => [
        'cancel_policy' => 'at_period_end',   // or 'immediately_with_refund'
        // ...
    ],
],
```

| Policy                    | Behaviour                                  |
| ------------------------- | ------------------------------------------ |
| `at_period_end`           | Grace period then canceled (default)       |
| `immediately`             | Canceled instantly, no grace period        |
| `immediately_with_refund` | Canceled instantly; prorated refund issued |

When `$immediately` is `false`, the per-plan policy is honoured. When `$immediately` is `true`, the subscription is always canceled instantly regardless of the plan policy.

## Checking cancellation status

```php theme={null}
$subscription = $user->subscription();

$subscription->onGracePeriod();     // true when in Grace status
$subscription->canceled_at;         // when cancel was requested
$subscription->ends_at;             // when access actually ends
```

The `ManagesBilling` trait also provides:

```php theme={null}
$user->onGracePeriod();             // default slot
$user->onGracePeriod('team');       // named slot
```

## Resuming a canceled subscription

A subscription in `Grace` status can be un-canceled before `ends_at`:

```php theme={null}
use Pixelworxio\Subscribd\Actions\ResumeSubscription;

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

This reinstates the subscription at the gateway, clears the `canceled_at` and `ends_at` dates, and sets the status back to `Active`.

## Listening to cancellation events

```php theme={null}
use Pixelworxio\Subscribd\Events\SubscriptionCanceled;

Event::listen(SubscriptionCanceled::class, function (SubscriptionCanceled $event): void {
    $billable = $event->subscription->billable;
    $plan     = $event->subscription->plan;

    // Trigger your off-boarding or win-back sequence
    Mail::to($billable->billingEmail())->send(new CancellationConfirmationMail($plan));
});
```

## Canceling all subscriptions on account deletion

```php theme={null}
// App\Models\User
protected static function booted(): void
{
    static::deleting(function (User $user): void {
        $user->subscriptions()
            ->whereIn('status', ['active', 'trialing', 'grace', 'paused'])
            ->each(function ($subscription): void {
                app(CancelSubscription::class)->execute($subscription, immediately: true);
            });
    });
}
```

## The SubscriptionManager Livewire component

The `subscription-manager` component includes a cancel flow with an optional confirmation modal and resume button for grace-period subscriptions:

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

See [Livewire Components](/components/livewire) for props and events.

## Next steps

* **[Pausing](/subscriptions/pausing)** — Pause billing without canceling
* **[Dunning](/advanced/dunning)** — Retry failed payments before a subscription is canceled
* **[Hooks and Events](/advanced/hooks-and-events)** — Full event reference