Skip to main content

React to a free buy-up grant, separately from a purchase

Premium Beginner

When a podcaster prices a buy-up at 0 on a billing period, subscribers on that period are given it, and nobody pays. That is a different event from a purchase, and it has its own action: benecaster_buyup_auto_granted.

benecaster_buyup_purchased does not fire for these subscribers, deliberately. Anything that thanks a buyer or records revenue stays correct by listening only to the purchase. Anything that provisions access, such as a download link, a community role or a CRM tag, should almost certainly run for both, so register the same callback on each rather than assuming the purchase covers everyone who holds the buy-up.

benecaster_buyup_auto_granted fires in four situations: a billing period’s price becomes 0 and everyone already on it is given the buy-up, except anyone who declined it; someone signs up on that period and leaves the included buy-up ticked; a subscriber’s switch onto that period takes effect with it ticked; and a subscriber adds a free buy-up back from their account page. One callback covers all four, and the grant is already recorded when it runs.

Don’t assume the subscriber is getting it for the first time. The account-page case fires for someone who had the buy-up, removed it, and has now added it back, so a welcome email or a one-time bonus can go out twice. Check your own records first if that matters.

If you need a buy-up’s Stripe Price to exist, listen to benecaster_buyup_prices_provisioned, not to the buy-up definition actions. Those fire before the Prices are created.

Code

<?php
// Somebody bought it: thank them, and count the money.
add_action( 'benecaster_buyup_purchased', function ( $user_id, $buyup_id, $show_id ) {
    my_send_thanks_for_buying( $user_id, $buyup_id );
    my_record_buyup_revenue( $buyup_id, $show_id );
}, 10, 3 );

// Somebody was GIVEN it because their billing period includes it, or added
// a free one back from their account page. No money moved — so a "thanks for
// your purchase" email here would be wrong, and a revenue line would be a
// false number.
add_action( 'benecaster_buyup_auto_granted', function ( $user_id, $buyup_id, $show_id ) {
    my_send_included_with_your_plan_note( $user_id, $buyup_id );
}, 10, 3 );

// Fulfilment that both should reach — register the same callback on both,
// rather than assuming the purchase hook covers everyone who holds it.
add_action( 'benecaster_buyup_purchased',     'my_provision_buyup_access', 10, 3 );
add_action( 'benecaster_buyup_auto_granted',  'my_provision_buyup_access', 10, 3 );

View on GitHub →

Hooks Used

Need this built rather than just documented? See our services →