Promote to Bridge — Grace Period

Promote to Bridge moves subscribers out of Benecaster’s built-in membership system and into an external membership plugin. It runs in that direction only — there is no reverse wizard that moves subscribers from an external plugin into built-in membership, and no way to promote between two external plugins. See Promote to Bridge — Overview for the full picture.

When you run the Promote to Bridge wizard, each promoted subscriber is given a grace period — a window during which their existing Benecaster feed token continues to work even though they are no longer being managed by the built-in membership system. Subscribers keep the same feed token and URL throughout — nothing about their feed changes when they promote successfully. Only which system Benecaster checks to confirm they’re still an active member changes. The grace period gives subscribers time to complete setup in the destination membership plugin before their old feed token is revoked. On default settings that URL does not stop working — it falls back to your public feed, because the per-show Serve the public feed on an invalid token setting is on by default and governs subscriber-level failures like this one. Turn it off for the show and the URL returns an error instead.

---

How the Grace Period Works

At the moment the wizard runs, Benecaster writes a promote_grace_period_ends_at date to each promoted subscriber’s record. The daily cron (GracePeriodExpiryCheck) evaluates all rows with a non-null value on this column:

Reminder pass — 6 to 8 days before expiry, the cron sends a promote_grace_reminder email. The two-day width is what stops it sending every day: the cron only looks at rows falling inside that bracket, and under normal daily cadence a row passes through it once. The width also absorbs a missed tick, which matters because WP-Cron needs web traffic to fire and a quiet site can skip a calendar day.

Worth knowing where that degrades: if cron misses several days in a row, a subscriber can fall inside the bracket on two separate ticks and receive the reminder twice. Nothing tracks that a reminder was already sent, so the second one is not suppressed.

Expiry pass — when promote_grace_period_ends_at is in the past, the cron first checks, automatically and by default, whether the subscriber is confirmed active in the destination plugin. If they are, their token is kept and none of the rest of this pass runs — no revoke, no benecaster_promote_grace_expired action, no promote_grace_expired email. If they are not (or automatic detection can’t tell, for instance because the destination plugin is deactivated), the cron revokes the subscriber’s feed token, fires the benecaster_promote_grace_expired action, and sends a promote_grace_expired email, exactly as before this check existed.

A subscriber who bought episodes outright is not revoked. Their token is converted instead: same feed URL, still active, serving your public episodes plus what they bought. The promote_grace_expired email is still sent, because the grace period did end, and the promotion is marked expired so it does not fire again. A subscriber who bought nothing is revoked as described above.

⚠ A kept token does not resolve the row. The check re-runs from scratch on every daily tick, so a subscriber kept today reverts to a normal revoke on the next tick if they later cancel in the destination plugin. The row’s grace-deadline badge in Promotion History still shows as past-due while the subscriber is being kept this way — nothing here marks anyone re-authorized. See Promote to Bridge — Overview → Re-authorization for what does.

After expiry, the subscriber’s record retains the promoted_to_bridge field (the target bridge slug) so their history is visible in the Promotion History panel.

---

Subscriber Experience

On the subscriber account page, subscribers who are in an active grace period see an amber banner. The date and the plugin name are filled in automatically — a subscriber moving to WooCommerce Subscriptions sees:

Your membership is being transferred.
Your current feed URL works until 14 September 2026. Complete your setup in WooCommerce Subscriptions before then to avoid interruption.

The plugin name comes from the destination bridge you selected in the wizard, so it matches whatever your subscribers will actually see when they get there.

The banner disappears after the grace period ends.

---

Grace Period Emails

Two managed email types fire during the grace period lifecycle:

Both emails are transactional (they cannot be opted out of individually). Both support the merge tags:

To customize these email templates, see Customizing Emails.

---

Managing Grace Periods

From Settings → Subscription → Promotion History, you can manage individual subscriber grace periods:

Extend — adds days to the current expiry date. Useful if a subscriber needs extra time to complete setup. The number you type is used exactly as typed: the benecaster_promote_grace_length_days filter described below deliberately does not apply here, so a site varying grace lengths in code cannot make this panel report a change it did not make.

Clear — removes the grace period marker and re-enables the subscriber’s token. Use this when a subscriber who has completed setup in the destination plugin has already had their token revoked.

There is no bulk grace-period management in V1.

---

Status: expired_grace

Subscribers whose grace period has ended have their subscription status set to expired_grace. This status is distinct from cancelled — it indicates the subscription ended because of a bridge promotion, not a cancellation event.

---

For Developers

• benecaster_promote_grace_expiry_should_revoke — filter; veto an expiry before anything happens. This is the same filter automatic re-authorization detection uses internally, so its default return value can now arrive as false — where it was always true before automatic detection existed — whenever the destination plugin confirms the subscriber active. Your own code can add further conditions on top for a subscriber your code can see has finished setting up in the destination plugin.
• benecaster_promote_grace_length_days — filter; vary the grace length per tier or per subscriber instead of using one number for the whole run. Applies to the wizard only, not to Extend
• benecaster_promote_grace_cleared — action; fires after a grace period is cleared from Promotion History
• benecaster_promote_grace_extended — action; fires after a grace period is extended from Promotion History
• benecaster_promote_grace_expired — action fired on expiry; args: (int $user_id, int $show_id, string $tier_slug). Does not fire when an expiry is vetoed
• REST API for extending and clearing grace periods: Promote to Bridge REST API