Dunning

When an invoice payment fails, Subscribd automatically retries the charge according to a configurable dunning schedule. Subscriptions that exhaust all retries without a successful payment are marked expired and access is revoked.

Default retry schedule

Out of the box, Subscribd retries failed payments at:

24 hours after initial failure
72 hours after initial failure
168 hours (7 days) after initial failure

If all three retries fail, the subscription moves to expired and the SubscriptionExpired event is fired.

Configuration

// config/subscribd.php
'dunning' => [
    'strategy'       => \Pixelworxio\Subscribd\Dunning\ConfigDrivenDunningStrategy::class,
    'retry_after'    => [24, 72, 168],   // hours after initial failure
    'notify_at'      => [72, 120],       // hours — fires PaymentRetryFailed at these points
    'grace_days'     => env('SUBSCRIBD_GRACE_PERIOD_DAYS', 3),
    'cancel_on_fail' => env('SUBSCRIBD_CANCEL_ON_DUNNING_FAIL', true),
],

The retry_after array defines when retries are attempted, in hours after the first failure. You can add or remove entries to suit your billing cycle. For example, a weekly billing cycle might use [24, 96, 240].

How dunning works

Payment fails — gateway fires invoice.payment_failed (or equivalent). The subscription moves to past_due.
Retry job scheduled — a RetryInvoice job is queued for each interval in retry_after.
Retry succeeds — the invoice is marked paid, the subscription returns to active, and InvoicePaid is fired.
Retry fails — PaymentRetryFailed is fired if the current hour matches a notify_at threshold.
All retries exhausted — if cancel_on_fail is true (default), the subscription is marked expired and SubscriptionExpired is fired.

Custom dunning strategy

Implement Pixelworxio\Subscribd\Contracts\DunningStrategy to replace the built-in schedule with custom logic:

<?php

namespace App\Billing;

use Pixelworxio\Subscribd\Contracts\DunningStrategy;
use Pixelworxio\Subscribd\Models\Invoice;

class MyDunningStrategy implements DunningStrategy
{
    /**
     * Return retry delay in hours for the given attempt number (1-indexed).
     * Return null to stop retrying.
     */
    public function retryAfterHours(Invoice $invoice, int $attempt): ?int
    {
        return match ($attempt) {
            1 => 24,
            2 => 72,
            3 => 168,
            default => null,
        };
    }

    public function shouldCancelOnFailure(Invoice $invoice): bool
    {
        return true;
    }
}

'dunning' => [
    'strategy' => \App\Billing\MyDunningStrategy::class,
],

Notifying customers during dunning

Listen to PaymentRetryFailed to send reminder emails or in-app notifications:

use Pixelworxio\Subscribd\Events\PaymentRetryFailed;

class SendPaymentRetryFailedNotification
{
    public function handle(PaymentRetryFailed $event): void
    {
        $event->subscription->billable->notify(new PaymentActionRequiredNotification($event->invoice));
    }
}

Event::listen(PaymentRetryFailed::class, SendPaymentRetryFailedNotification::class);

Manually retrying an invoice

Retry a specific invoice immediately, bypassing the dunning schedule:

use Pixelworxio\Subscribd\Actions\RetryInvoice;

app(RetryInvoice::class)->execute($invoice);

This attempts a charge on the customer’s default payment method and returns the updated Invoice model. If the charge succeeds, the subscription returns to active.

Grace period

When a subscription enters past_due, the billable retains access for grace_days (default: 3) before the subscription is expired. Configure this globally or per plan:

SUBSCRIBD_GRACE_PERIOD_DAYS=5

Or in config/subscribd.php:

'dunning' => [
    'grace_days' => 5,
],

Updating payment methods

When a customer updates their payment method during a past_due period, trigger an immediate retry:

use Pixelworxio\Subscribd\Actions\RetryInvoice;

// After payment method updated — surface the failed invoice and retry
$invoice = $user->invoices()->failed()->latest()->first();

if ($invoice) {
    app(RetryInvoice::class)->execute($invoice);
}

Checking dunning status

$user->subscription()->status->value; // 'past_due'

$user->pastDue();   // true while in dunning
$user->subscribed(); // true until grace_days expires

Next steps

Hooks and Events — Events fired during the dunning cycle
Webhooks — Receiving payment failure events from gateways

Getting Started

Billing Scenarios

Subscriptions

Gateways

Entitlements

Invoices & Charges

Coupons

Components

Advanced

Dunning

Dunning

Default retry schedule

Configuration

How dunning works

Custom dunning strategy

Notifying customers during dunning

Manually retrying an invoice

Grace period

Updating payment methods

Checking dunning status

Next steps

​Dunning

​Default retry schedule

​Configuration

​How dunning works

​Custom dunning strategy

​Notifying customers during dunning

​Manually retrying an invoice

​Grace period

​Updating payment methods

​Checking dunning status

​Next steps

Dunning

Default retry schedule

Configuration

How dunning works

Custom dunning strategy

Notifying customers during dunning

Manually retrying an invoice

Grace period

Updating payment methods

Checking dunning status

Next steps