Skip to main content

​
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: 
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: 
// 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: 
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: 
// config/subscribd.php
'plans' => [
    'lifetime' => [
        'cancel_policy' => 'immediately',
        // ...
    ],
    'pro' => [
        'cancel_policy' => 'at_period_end',   // or 'immediately_with_refund'
        // ...
    ],
],
PolicyBehaviour
at_period_endGrace period then canceled (default)
immediatelyCanceled instantly, no grace period
immediately_with_refundCanceled 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

$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: 
$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: 
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

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

// 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: 
<livewire:subscribd::subscriber.subscription-manager />
See Livewire Components for props and events.

​
Next steps

  • Pausing — Pause billing without canceling
  • Dunning — Retry failed payments before a subscription is canceled
  • Hooks and Events — Full event reference