WooSubscriptionsBridge

Benecaster\Bridge\Bridges\WooSubscriptionsBridge

The built-in bridge for WooCommerce Subscriptions. Connects Benecaster to WooCommerce subscription products, mapping each product to a Benecaster tier.

Slug: woo-subscriptions
Detection: class_exists('WC_Subscriptions') — true when WooCommerce Subscriptions is active alongside WooCommerce core.

Tier Resolution

get_user_tier( int $user_id, int $show_id ) works as follows:

1. Calls wcs_get_users_subscriptions( $user_id ) to retrieve all WooCommerce subscription objects for the user.
2. Filters to subscriptions with status 'active'.
3. For each active subscription, iterates its line items to get the WooCommerce product IDs purchased.
4. For each product ID, looks up a matching row in benecaster_tier_map where plugin_slug = 'woo-subscriptions' and external_tier_id matches the product ID.
5. Filters to rows where show_id matches the given $show_id.
6. Returns the internal_tier_slug of the first matching row, or null if none matches.

The first match wins. If a subscriber holds multiple active subscriptions mapped to tiers for the same show, the iteration order (as returned by wcs_get_users_subscriptions) determines which tier is returned.

Required setup: At least one row must exist in benecaster_tier_map with plugin_slug = 'woo-subscriptions' and external_tier_id matching a WooCommerce product ID of type subscription or variable-subscription. Without a mapped row, get_user_tier() always returns null. See Mapping Your Membership Tiers.

Tier Listing

get_all_tiers( int $show_id ) returns all published WooCommerce products of type subscription and variable-subscription via wc_get_products(). One entry is returned per product — variable subscription parent products are returned as a single entry; individual variations are not enumerated separately. The $show_id parameter is accepted but not used — WooCommerce products are site-wide.

Each entry is array{id: int, name: string, price: float}, where id is the product ID as an integer, name is the product title, and price is the product’s regular price. For variable subscription products, price is the minimum variation price. A price of 0.00 marks the tier as free — it will not count toward the Benecaster license tier limit. This list populates the tier mapping UI.

Tier Save Events

on_tier_saved() hooks into WooCommerce’s product save pipeline, filtered to subscription and variable-subscription product types. The same hook fires for both new product creation and updates (including price changes). Specific hook name TBD — verify against WooCommerce docs before implementation (candidates: woocommerce_update_product, woocommerce_new_product, or woocommerce_admin_process_product_object). Fires the callback with array{id: int, name: string, price: float}.

WooCommerce Subscriptions Hooks

WooSubscriptionsBridge hooks into the following WooCommerce Subscriptions status-transition actions:

WooCommerce hook	Bridge event	Notes
woocommerce_subscription_status_pending_to_active	on_subscription_activated	New initial subscription activated. Source: 'new'.
woocommerce_subscription_status_cancelled_to_active	on_subscription_activated	Re-subscription after a previous cancellation. Source: 'resubscribe'.
woocommerce_subscription_status_on-hold_to_active	on_subscription_activated	Subscription returning to Active from On Hold — payment failure recovered. Source: 'resubscribe'.
woocommerce_subscription_status_cancelled	on_subscription_cancelled	Subscription cancelled by subscriber or admin.
woocommerce_subscription_renewal_payment_complete	on_subscription_renewed	Successful recurring payment. Receives $subscription, $renewal_order.
woocommerce_subscription_status_on-hold	on_payment_failed	Subscription suspended after a failed payment. Feed access continues; resolved when subscription returns to Active or is cancelled.

Known Limitation: No Native Plan-Change Event

WooCommerce Subscriptions has no dedicated event for plan switches (subscription product upgrades or downgrades). When a subscriber switches products, WooCommerce cancels the old subscription and creates a new one. on_subscription_changed() is a documented no-op — it registers no hooks.

Benecaster responds to the cancel and new-activation events separately: the old tier is revoked when the cancellation fires, and a new token for the new tier is generated when the activation fires. The subscriber’s feed URL changes because a new token is issued.

Code that depends on benecaster_subscription_tier_changed will not fire for WooCommerce Subscriptions product switches. Use benecaster_subscription_activated with $source = 'resubscribe' as the closest available signal.

Setup Notes

No custom code is needed to use WooSubscriptionsBridge. It is configured, connected, and tested entirely through the Benecaster admin interface.

See WooCommerce Subscriptions Setup for the complete setup walkthrough, including how to connect the bridge, map subscription products to tiers, and test the connection.