Subscription Actions Reference

📘
These actions are not enabled by default.
You will need to enable specific actions on your app.surecart.com developer section - Manage Webhooks [How to Edit Webhook Endpoint]

Examples

Subscription Renewal

In this example, we will add a renewal count to a WordPress user. This can be used to keep track of how many renewals have happened for a specific subscription, product or price for example.

add_action( 'surecart/subscription_renewed', function( $subscription, $webhook_data = [] ) {
  // this is not the price we are looking for.
  if ( 'db6021f6-e972-4006-857c-c27bff9fcbeb' !== $subscription->price ) {
    return;
  }
  
  // get the WP user from the subscription.
  $wp_user = $subscription->getUser();
  
  // the wp user does not exist because maybe it was deleted.
  if ( empty( $wp_user ) ) {
    return;
  }
  
  // get the current renewals count of the user.
  $renewals_count = (int) get_post_meta( $wp_user->ID, 'renewal_acount', true );

  // increment the renewals count.
  update_post_meta( $wp_user->ID, 'renewal_count', $renewals_count++ ); 
}, 10, 2 );

Subscription Set To Cancel

In this example, we will add user meta to the account for when the subscription is set to cancel. This way we can display a banner elsewhere on our site to inform them they are losing access. It's useful to store this locally, on the WordPress installation so that your site is not slowed down by API calls to SureCart servers during the PHP request lifecycle.

/**
 * When the subscription is set to cancel, store this on the WP user.
 */
add_action( 'surecart/subscription_set_to_cancel', function( $subscription, $webhook_data = [] ) {
  // this is not the price we are looking for.
  if ( 'db6021f6-e972-4006-857c-c27bff9fcbeb' !== $subscription->price ) {
    return;
  }
  
  // get the WP user from the subscription.
  $wp_user = $subscription->getUser();
  
  // the wp user does not exist because maybe it was deleted.
  if ( empty( $wp_user ) ) {
    return;
  }

  // store this on the user.
  update_post_meta( $wp_user->ID, 'cancelling', true ); 
}, 10, 2 );

Then we will want to do the opposite if the subscription is "un-cancelled", which means it's made active again.

/**
 * When the subscription is active, store this on the WP user.
 */
add_action( 'surecart/subscription_made_active', function( $subscription, $webhook_data = [] ) {
  // this is not the price we are looking for.
  if ( 'db6021f6-e972-4006-857c-c27bff9fcbeb' !== $subscription->price ) {
    return;
  }
  
  // get the WP user from the subscription.
  $wp_user = $subscription->getUser();
  
  // the wp user does not exist because maybe it was deleted.
  if ( empty( $wp_user ) ) {
    return;
  }

  // store this on the user.
  update_post_meta( $wp_user->ID, 'cancelling', false ); 
}, 10, 2 );

Reference

surecart/subscription_canceled

Occurs when a subscription's status changes to canceled

surecart/subscription_created

Occurs when a subscription is created

surecart/subscription_completed

Occurs when a subscription's status changes to completed

surecart/subscription_made_active

Occurs when a subscription's status changes to active

surecart/subscription_made_trialing

Occurs when a subscription's status changes to trialing

surecart/subscription_renewed

Occurs when a subscription renews

surecart/subscription_set_to_cancel

Occurs when a subscription is set to cancel at the end of the current billing period

surecart/subscription_updated

Occurs when a subscription is updated

surecart/period_paid

Occurs whenever a billing period is paid. A common use-case is when a subscription renews.