Skip to main content
Subscribd dispatches a Laravel event at every significant billing lifecycle transition. All events live in Pixelworxio\Subscribd\Events\ and are fired after the corresponding database write completes, so event listeners always work with fully persisted model state. Register listeners in your EventServiceProvider using standard Laravel patterns — closure listeners, queued listeners, and subscriber classes all work.

​
Registering listeners

use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;
use Pixelworxio\Subscribd\Events\PaymentFailed;
use Pixelworxio\Subscribd\Events\SubscriptionCanceled;
use Pixelworxio\Subscribd\Events\SubscriptionCreated;
use Pixelworxio\Subscribd\Events\SubscriptionUpdated;
use Pixelworxio\Subscribd\Events\InvoiceCreated;
use Pixelworxio\Subscribd\Events\PaymentSucceeded;
use Pixelworxio\Subscribd\Events\TrialEnding;

class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        SubscriptionCreated::class  => [/* your listener classes */],
        SubscriptionUpdated::class  => [/* your listener classes */],
        SubscriptionCanceled::class => [/* your listener classes */],
        InvoiceCreated::class       => [/* your listener classes */],
        PaymentSucceeded::class     => [/* your listener classes */],
        PaymentFailed::class        => [/* your listener classes */],
        TrialEnding::class          => [/* your listener classes */],
    ];
}
Or register closure listeners in AppServiceProvider::boot(): 
Event::listen(PaymentFailed::class, function (PaymentFailed $event) {
    // handle inline
});

​
Events reference

​
SubscriptionCreated

Fired after a new subscription is persisted to the database and confirmed on the gateway. Payload: $event->subscription — the newly created Subscription model. 
Event::listen(SubscriptionCreated::class, function (SubscriptionCreated $event) {
    $event->subscription->billable->notify(new WelcomeNotification());
});

​
SubscriptionUpdated

Fired after a plan swap completes — both the gateway record and the local Subscription model have been updated. Payload: $event->subscription — the updated Subscription model with the new plan_id. 
Event::listen(SubscriptionUpdated::class, function (SubscriptionUpdated $event) {
    Cache::forget("entitlements.{$event->subscription->billable_id}");
});

​
SubscriptionCanceled

Fired after a cancellation is recorded. The subscription may be in grace status (cancel at period end) or canceled status (immediate cancellation) at the time the event fires. Payload: $event->subscription — the canceled Subscription model. 
Event::listen(SubscriptionCanceled::class, function (SubscriptionCanceled $event) {
    $event->subscription->billable->notify(new SubscriptionCanceledNotification());
});

​
InvoiceCreated

Fired when a new invoice is created, before payment is attempted. Useful for adding line items, applying tax, or logging. Payload: $event->invoice — the newly created Invoice model. 
Event::listen(InvoiceCreated::class, function (InvoiceCreated $event) {
    logger()->info("Invoice created", ['invoice_id' => $event->invoice->id]);
});

​
PaymentSucceeded

Fired after an invoice is paid successfully. Use it to provision access, send receipts, or update your records. Payload: $event->invoice — the paid Invoice model with status = 'paid'. 
Event::listen(PaymentSucceeded::class, function (PaymentSucceeded $event) {
    Mail::to($event->invoice->billable->billingEmail())
        ->send(new ReceiptMail($event->invoice));
});

​
PaymentFailed

Fired when a payment attempt fails — either on the initial charge or during a dunning retry. Both $event->invoice and the human-readable $event->message from the gateway are available. Payload: $event->invoice — the Invoice model with status = 'failed'. $event->message — gateway error string. 
Event::listen(PaymentFailed::class, function (PaymentFailed $event) {
    // $event->invoice — the Invoice model
    // $event->message — gateway error string
    Mail::to($event->invoice->billable->billingEmail())
        ->send(new PaymentFailedMail($event));
});

​
TrialEnding

Fired when a trial subscription is approaching its end. Subscribd fires this event before the trial expires so you can prompt the subscriber to add a payment method. Payload: $event->subscription — the trialing Subscription model. $event->daysRemaining — integer count of days left in the trial. 
Event::listen(TrialEnding::class, function (TrialEnding $event) {
    // $event->subscription — the trialing Subscription model
    // $event->daysRemaining — int
    if ($event->daysRemaining <= 3) {
        $event->subscription->billable->notify(
            new TrialEndingNotification($event->daysRemaining)
        );
    }
});

​
Event summary

EventPropertyTypeWhen fired
SubscriptionCreated$subscriptionSubscriptionAfter a new subscription is persisted
SubscriptionUpdated$subscriptionSubscriptionAfter a plan swap completes
SubscriptionCanceled$subscriptionSubscriptionAfter a cancellation is recorded
InvoiceCreated$invoiceInvoiceWhen a new invoice is created
PaymentSucceeded$invoiceInvoiceAfter successful payment
PaymentFailed$invoice, $messageInvoice, stringAfter a failed payment attempt
TrialEnding$subscription, $daysRemainingSubscription, intWhen a trial is nearing its end
All events are standard Laravel events and work with any driver — synchronous, queued, or broadcast. Queued listeners are the recommended approach for side effects like sending email or calling external APIs.