Membership Plugin Bridges — Developer Reference
A bridge is the layer between a membership plugin and Benecaster. It answers which tier a user holds on a show and whether it is active, and it reports the plugin’s subscription events (activated, cancelled, changed, renewed, payment failed) so Benecaster can issue and revoke feed tokens. Benecaster never talks to a membership plugin directly. For how bridges work from the podcaster’s side, see Subscription Plugin Overview.
This page is for two kinds of developer: one writing a bridge for a membership plugin Benecaster doesn’t ship one for, and one whose add-on needs to react to bridges.
Writing a Custom Bridge
Benecaster ships bridges for MemberPress, WooCommerce Subscriptions, Paid Memberships Pro and Restrict Content Pro, plus its own Built-in Membership. Any other membership plugin can be connected by writing a bridge for it.
A custom bridge is a PHP class implementing Benecaster\Bridge\BridgeInterface, typically delivered as a small companion plugin beside the membership plugin it connects. Once the companion plugin is installed and activated, the bridge appears in the bridge picker alongside the built-in ones and behaves identically: tier mapping, feed access and everything downstream work the same way.
See Integrate a Custom Membership Plugin for a complete, working example. The sections below cover the parts of the contract that are easy to get wrong.
Levels Your Plugin No Longer Sells
A level that still has members but takes no new signups should still be returned by your bridge’s get_all_tiers(), marked 'accepts_signups' => false. Benecaster then lists it on Tier Mapping with a Signups closed label, counts and prices its members like any other level, and leaves it off [benecaster_pricing_table] and [benecaster_subscribe].
Leaving the level out instead hides its members’ tier from mapping and from the revenue estimate. A bridge that doesn’t set the key is treated as open.
Reporting a Lapse, Not Just a Cancellation
The on_subscription_cancelled() callback your bridge invokes takes an optional third argument: $callback( int $user_id, int $show_id, string $reason = 'cancelled' ). Pass 'expired' when your membership plugin can tell that a membership lapsed (a fixed term ran out, or renewals were attempted and gave up) rather than being cancelled by the subscriber. With two arguments the reason is 'cancelled'.
Report the lapse at all, even if you can’t tell the reason. A bridge that never calls on_subscription_cancelled() for an expiry leaves that member’s token active indefinitely: still counted as a paying subscriber, and never sent the cancellation email.
Reporting 'expired' also fires benecaster_subscription_expired on top of the standard cancellation handling, so an add-on can send lapse-specific win-back messaging instead of a “sorry to see you go” message.
Supporting Sync Existing Members
Sync Existing Members gives members who were already in the plugin before it was connected their feed links. A custom bridge gets it by also implementing the optional Benecaster\Bridge\BridgeMemberListing interface: one paged list of active members per level, and each member’s earliest start date. The Restrict Content Pro and Paid Memberships Pro bridges implement it.
See Let Sync Existing Members work with a custom bridge. For code that reacts to synced members, see benecaster_subscription_synced.
Your Source Data Is Keyed by Email; Benecaster Is Keyed by User ID
This is the mismatch every custom bridge hits first. A membership plugin export, a webhook payload or a CSV of members gives you email addresses, and Benecaster’s lookup functions take a WordPress user ID. Two functions close the gap:
benecaster_get_user_id_by_subscriber_email()resolves one address to one user ID. It is the cheap one, and the one to call inside a loop over an import.benecaster_get_subscriber_data()returns the whole record for one subscriber on one show, keyed by email: user ID, display names, tier, token status and revocation reason. Use it when you want more than the ID, rather than resolving an ID and then making three more calls.
Benecaster subscribers are WordPress users; there is no subscriber record without a WordPress account. So neither function can tell you about an address with no account, and both return an empty result rather than creating one.
See Looking Up a Subscriber for the full decision matrix.
Enabling “Add Subscriber Manually”
The Add Subscriber Manually admin action is available by default only on shows using Built-in Membership. A bridge can unlock it for shows that use it in two steps.
1. Implement BridgeInterface::create_manual_membership() on the bridge class. Do not use ManualMembershipUnsupportedTrait, which is a throwing stub for bridges that cannot support this. Your implementation should:
- create the member record in the target plugin’s data model;
- call
TokenManager::generate()to mint a Benecaster token; - stamp
is_manual_grant = 1(andmanual_expiry_atwhen an expiry was requested) on the token row throughTokenRepository::set_manual_grant(); - return
{ subscription_id: int, token_prefix: string }.
2. Return true from benecaster_bridge_supports_manual_membership for your bridge’s slug:
add_filter( 'benecaster_bridge_supports_manual_membership', function( bool $default, string $bridge_slug ): bool {
if ( 'acme_membership' === $bridge_slug ) {
return true;
}
return $default;
}, 10, 2 );
With both in place, the Add Subscriber Manually button appears on shows bound to your bridge, and POST /shows/{id}/subscribers/manual routes through your implementation. See the Add Manual Membership Support to a Custom Bridge recipe for a complete example.
Reacting When a Bridge Is Connected
The benecaster_bridge_connected action fires each time a bridge is saved for a show, whether from the Setup Wizard or from Benecaster → Shows → [your show] → Settings → Subscription. It does not fire when a bridge is cleared. Arguments: (string $bridge_slug, int $show_id).
Use it from an add-on to react to a connection, for example to set up a default integration or pre-fill data from the newly connected plugin.
Suppressing an Email for One Plugin
Each Benecaster email has a per-show on/off switch. To suppress one programmatically, for example the Welcome email only when a particular membership plugin add-on is active, or to send it through your own transactional email provider instead, use the type-specific filter benecaster_email_should_send_{type} (for the Welcome email, benecaster_email_should_send_welcome). The filter runs after the per-show switch, so it is never reached for an email type that is switched off in settings. See benecaster_email_should_send.
See Also
Need this built rather than just documented? See our services →