benecaster_promote_grace_expiry_should_revoke

Decides whether a transferred subscriber’s grace period should actually end. Runs once per past-due row at the top of the daily expiry cron. Promote-to-Bridge checks the destination bridge’s is_user_active( $user_id, $show_id ) first, for the four built-in bridges, and sets $should_revoke to false when the subscriber is confirmed active there (true otherwise, including when the bridge can’t answer — e.g. a deactivated plugin). Your callback receives that computed default and has the final word: return it unchanged to defer to the built-in check, or override it either direction. Return false to veto.

A veto skips the entire expiry, not just the revoke — the token revocation, the expired_grace status transition, the promote_grace_expired email, and the benecaster_promote_grace_expired action. That is deliberate: skipping only the revoke would email a subscriber that their subscription had ended while their feed still worked.

A veto means “not today”, not “never”. Vetoing does not clear promote_grace_period_ends_at, so the row stays past-due and the next daily tick asks again. That built-in re-ask is why there is no “defer by N days” return value — and why one would not work anyway, since 1 is truthy and would read as consent.

A callback that only ever returns false leaves the row permanently past-due, and Promotion History will show it as in-grace with a date that has already elapsed. The pattern to follow is veto today, then resolve the row properly — PromotionService::extend_grace_period() to push the deadline out, or clear_grace_period() when the subscriber has re-authorized.

The return is compared with a strict true !==, so a truthy non-boolean vetoes rather than consenting. Return a real boolean.

Automatic re-authorization detection, described on Promote to Bridge — Overview, is built on this same filter for the four built-in bridges. Use it yourself for what that built-in check doesn’t cover: a custom bridge, a check more specific than plain active/inactive, or resolving a row the built-in check merely vetoed (it never calls clear_grace_period()).