Skip to main content
CancelSubscription handles ending a subscription. The default behavior cancels at the end of the current billing period, giving the subscriber access through the period they have already paid for. You can also cancel immediately when access should end right away. Both paths update the gateway record and persist the status change in your database before firing SubscriptionCanceled.

​
Calling styles

Use cancel() or cancelSubscription() on a BillableContext. Both methods delegate to CancelSubscription internally.
use Pixelworxio\Subscribd\Facades\Subscribd;

// Cancel at period end (default behavior)
Subscribd::for($user)->cancel();

// Cancel immediately — access ends now
Subscribd::for($user)->cancel('default', immediately: true);

// Cancel a named add-on subscription immediately
Subscribd::for($user)->cancelSubscription('addons', immediately: true);

​
Parameters

ParameterTypeRequiredDescription
$subscriptionSubscriptionYesThe subscription to cancel
$immediatelyboolNofalse = cancel at period end; true = cancel now. Defaults to the value of config('subscribd.cancel_policy')

​
Grace period behavior

When you cancel at period end, the subscription enters a grace period — it retains status = 'grace' until the current billing period expires. During the grace period:
  • $user->subscribed('default') returns true
  • $user->onGracePeriod('default') returns true
  • Entitlement checks continue to pass
  • The subscriber can resume the subscription (see below)
Once the billing period ends, a webhook from the gateway triggers the final status change to 'canceled'. 
// Check if the subscription is in the grace period
if ($user->onGracePeriod('default')) {
    // Show "Your subscription ends on {date}" message
}

​
Resuming during the grace period

A subscriber who cancels at period end can change their mind and reactivate before the period expires. Call resume() on the facade or use the ResumeSubscription action. 
// Resume before the grace period expires
Subscribd::for($user)->resume();
See PauseSubscription and ResumeSubscription for full resume documentation.

​
Subscription query scopes

Use Eloquent query scopes to find subscriptions in specific states. 
use Pixelworxio\Subscribd\Models\Subscription;

Subscription::active()->get();
Subscription::onGracePeriod()->get();
Subscription::canceled()->get();
Immediate cancellation bypasses the grace period entirely. The subscription moves directly from 'active' or 'trialing' to 'canceled' and the subscriber loses access immediately.

​
Global cancel policy

You can set the default cancellation behavior in config/subscribd.php. The per-call $immediately parameter always takes precedence. 
'cancel_policy' => 'at_period_end', // 'at_period_end' | 'immediately'

​
Events fired

SubscriptionCanceled is dispatched after the cancellation is recorded. Use it to revoke access, notify the subscriber, or clean up associated resources. 
use Pixelworxio\Subscribd\Events\SubscriptionCanceled;

Event::listen(SubscriptionCanceled::class, function (SubscriptionCanceled $event) {
    // $event->subscription — the canceled Subscription model
    $event->subscription->billable->notify(new SubscriptionCanceledNotification());
});