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.