`benecaster_license_grace_started`

Action Free Since v1.0.0

Fires from GraceExpiryTracker::on_license_invalid() on the first transition of the license into a payment-failed grace window. Subsequent /validate rejections with reason: payment_failed before recovery do not re-fire this action — the clock starts once and does not reset.

Only fires for reason: payment_failed. cancelled and license_not_found do not open a grace window and do not fire this action.

Use this action to surface “your payment failed — 30-day window has begun” warnings: publish an admin notice via NoticeManager, send a platform alert to an external monitoring service, or trigger a customer-facing email via a CRM integration.

Parameters

Name	Type	Default	Description
`$started_at`	`int`	—	Unix timestamp when the grace window opened (the time of the first payment_failed rejection)
`$reason`	`string`	—	The `reason` field from the /validate response that opened the grace window. Currently always 'payment_failed'; reserved for future expansion.

Examples

Send an external alert when the payment-failed grace window opens

add_action( 'benecaster_license_grace_started', function ( int $started_at, string $reason ): void {
    wp_remote_post( MY_MONITORING_WEBHOOK, [
        'body' => wp_json_encode( [
            'event'      => 'license_grace_started',
            'reason'     => $reason,
            'started_at' => $started_at,
            'site'       => home_url(),
        ] ),
    ] );
}, 10, 2 );

Notes

The grace window lasts 30 days. Once it elapses, benecaster_license_grace_expired fires on each cron pass and all active subscriber tokens are flagged over-limit. Recovery is via benecaster_license_grace_recovered.