Promote to Bridge — Grace Period
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. The grace period gives subscribers time to complete setup in the destination membership plugin before their old feed URL stops working.
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 and sets a transient so the reminder is not re-sent each day.
Expiry pass — when promote_grace_period_ends_at is in the past, the cron revokes the subscriber’s feed token, fires the benecaster_promote_grace_expired action, and sends a promote_grace_expired email.
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:
Your membership is being transferred.
Your current feed URL works until [date]. Complete your setup in [target plugin name] before then to avoid interruption.
The banner disappears after the grace period ends.
Grace Period Emails
Two managed email types fire during the grace period lifecycle:
| Email type | When it sends | Template file |
|---|---|---|
promote_grace_reminder |
6–8 days before expiry | promote-grace-reminder.php |
promote_grace_expired |
On expiry | promote-grace-expired.php |
Both emails are transactional (they cannot be opted out of individually). Both support the merge tags:
| Merge tag | Description |
|---|---|
{{tier_name}} |
The subscriber’s original native tier name |
{{grace_period_end_date}} |
The formatted expiry date |
{{target_plugin_name}} |
The name of the destination membership plugin |
To customise these email templates, see Customising 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.
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 in the benecaster_subscriptions table. This status is distinct from cancelled — it indicates the subscription ended because of a bridge promotion, not a cancellation event.
For Developers
GracePeriodExpiryCheck— the daily cron class that manages both passesSubscriptionRepositorygrace-period methods —set_promote_grace_period(),clear_promote_grace_period(),mark_promote_grace_expired(),find_grace_period_window()- [
benecaster_promote_grace_expired](/docs/benecaster_bridge_promote_complete/) — action fired on expiry; args:(int $user_id, int $show_id, string $tier_slug) - REST API for extending and clearing grace periods: Promote to Bridge REST API
