gform_subscription_canceled

Description

This action hook can be used to perform custom actions when a subscription has been canceled.

Usage

add_action( 'gform_subscription_canceled', 'your_function_name', 10, 3 );

or

add_action( 'gform_subscription_cancelled', 'your_function_name', 10, 3 );

Parameters

  • $entry Entry Object

    The entry from which the canceled subscription was originally generated.

  • $feed Feed Object

    The feed from which the subscription was originally generated.

  • $transaction_id string

    The transaction ID of the canceled subscription.

Examples

1. Run Custom Function

This example shows how to update your order on a fictional third party order fulfillment service.

add_action( 'gform_subscription_canceled', 'remove_user_privileges', 10, 3 );
function remove_user_privileges( $entry, $feed, $transaction_id ) {
	if ( ! function_exists( 'gf_user_registration' ) ) {
		return;
	}

	$user_id = gf_user_registration()->get_user_by_entry_id( rgar( $entry, 'id' ), true );

	if ( $user_id ) {
		// Using a function from a fictional third-party plugin to remove privileges from a user.
		mtp_remove_privileges( $user_id, $transaction_id );
	}
}

2. Downgrade User Role

This example shows how you can downgrade the user role when a subscription is canceled via one of the credit card based payment add-ons.

Note: This code requires User Registration version 3.0+.

add_action( 'gform_subscription_canceled', 'downgrade_user_role', 10, 2 );
function downgrade_user_role( $entry, $feed ) {
	if ( rgar( $feed, 'addon_slug' ) == 'gravityformspaypal' || ! function_exists( 'gf_user_registration' ) ) {
		return;
	}

	$user = gf_user_registration()->get_user_by_entry_id( $entry['id'] );
	if ( ! empty( $user ) && ! is_wp_error( $user ) ) {
		$user->set_role( 'pastsubscriber' );
	}
}

3. Mailchimp – Unsubscribe Member

This example shows how you can unsubscribe a member from a Mailchimp list when the subscription is canceled. This example requires Gravity Forms Mailchimp add-on version 4.0 or greater. It also requires that the entry which created the subscription was the same entry which subscribed the user to the Mailchimp list.

add_action( 'gform_subscription_canceled', function ( $entry ) {
	if ( ! class_exists( 'GF_MailChimp_API' ) ) {
		// Abort if the class for interacting with the Mailchimp API is not available.
		return;
	}

	// Get the Mailchimp feed which processed the entry and the Mailchimp API key.
	$feeds   = gf_mailchimp()->get_feeds_by_entry( $entry['id'] );
	$api_key = gf_mailchimp()->get_plugin_setting( 'apiKey' );

	if ( ! $feeds || rgblank( $api_key ) ) {
		// Abort if the entry was not processed by a MailChimp feed or if the API key is empty.
		return;
	}

	// Get the IDs of the Mailchimp list and the form field containing the email.
	$feed     = gf_mailchimp()->get_feed( $feeds[0] );
	$list_id  = rgars( $feed, 'meta/mailchimpList' );
	$email_id = rgars( $feed, 'meta/mappedFields_EMAIL' );

	if ( rgblank( $list_id ) || rgblank( $email_id ) ) {
		// Abort if the list or email field ID are missing.
		return;
	}

	// Get the email field value.
	$form  = GFAPI::get_form( $entry['form_id'] );
	$email = gf_mailchimp()->get_field_value( $form, $entry, $email_id );

	try {

		// Get the member info for the specified email and list.
		$mc_api = new GF_MailChimp_API( $api_key );
		$member = $mc_api->get_list_member( $list_id, $email );

		// Update the member status.
		$member['status'] = 'unsubscribed';
		$mc_api->update_list_member( $list_id, $member['email_address'], $member );
		gf_mailchimp()->log_debug( "gform_subscription_canceled: member status for {$email} updated to unsubscribed." );

	} catch ( Exception $e ) {
		// Abort if an error occurred when interacting with the MailChimp API.
		return;
	}
} );

4. Access webhook event

In some cases you may need access to the webhook event that initiated the subscription cancelation. This example demonstrates how to access that event object. Note: this object is only available if the request was initiated by a Stripe webhook.

add_action( 'gform_subscription_canceled', 'my_function', 10, 2 );
function my_function( $entry, $feed ) {

	// If data from the Stripe webhook event is needed (and this hook was initiated via a Stripe webhook request), you can access event data with the following line:
	$event = gf_stripe()->get_webhook_event();
	if ( $event ) {
		// Access webhook event data. For event object documentation, see: https://stripe.com/docs/api/events/object
	}

}

Placement

This code should be placed in the functions.php file of your active theme.

Source Code

do_action( 'gform_subscription_canceled', $entry, $feed, $transaction_id );

This action hook is located in GFPaymentAddOn::cancel_subscription() in includes/addon/class-gf-payment-addon.php.