Author: Predrag

Summary

Over time, membership sites accumulate large numbers of expired members — users whose memberships have lapsed and who no longer have active subscriptions or transactions. Manually removing these users one by one through the WordPress admin is not practical at scale. This document provides a custom code snippet that allows site administrators to identify and permanently delete expired members in bulk.

The solution uses a two-step process: a preview (dry run) mode that shows statistics on how many members would be removed, followed by a confirmation step that performs the actual deletion. This approach ensures administrators can review the impact before committing to permanent changes.

This document covers the full implementation process, including code setup, execution steps, and important post-cleanup actions. It also addresses common issues that may arise during the bulk removal process.

Troubleshooting

Removing Expired Members in Bulk

1) Too Many Expired Members to Remove Manually

Sites with long histories or high membership turnover can accumulate thousands of expired users. The default WordPress user management interface does not provide a built-in way to bulk-delete users based on membership expiry status. The custom snippet below queries the MemberPress members table directly to identify users with no active memberships, active transactions, or active trials.

How to Test/Fix:

Add the following code snippet using the WPCode plugin or by adding it to the child theme’s functions.php file. Review the MemberPress guide on adding custom code snippets for detailed instructions on both methods.

Important: Back up the database before proceeding. Use a staging environment to test the snippet before running it on a live site.

/**
 * MemberPress - Remove Expired Members Snippet
 *
 * Add this code to your theme's functions.php or as a mu-plugin
 *
 * USAGE:
 * 1. Add this code to functions.php (temporary)
 * 2. Visit: your-site.com/wp-admin/?remove-expired-members-snippet
 * 3. Review statistics shown in admin notice
 * 4. Click "Confirm Delete" button to actually delete
 * 5. Remove code after use
 *
 * IMPORTANT:
 * - BACKUP YOUR DATABASE FIRST!
 * - Always shows statistics first, then requires confirmation
 */
// Hook into admin_init to check for URL parameter
add_action('admin_init', 'mepr_remove_expired_members_handler');
function mepr_remove_expired_members_handler() {
   // Check if URL parameter is present
   if (!isset($_GET['remove-expired-members-snippet'])) {
       return;
   }

   // Security check
   if (!current_user_can('manage_options')) {
       wp_die('Access denied. Administrator access required.');
   }

   // Check MemberPress is active
   if (!class_exists('MeprUser')) {
       add_action('admin_notices', function() {
           echo '<div class="notice notice-error"><p><strong>Error:</strong> MemberPress plugin is not active.</p></div>';
       });
       return;
   }

   // ===== CONFIGURATION =====
   $batch_size = 100;         // Process in batches (reduce if timeout)
   $exclude_admins = true;    // Don't delete administrators
   // =========================

   // Check if this is a confirmation request
   $confirmed = isset($_GET['confirm']) && $_GET['confirm'] === 'yes' && isset($_GET['nonce']) && wp_verify_nonce($_GET['nonce'], 'mepr_delete_expired');

   if ($confirmed) {
       // Actually delete the members
       $results = mepr_process_expired_members_removal(false, $batch_size, $exclude_admins);
       add_action('admin_notices', function() use ($results) {
           mepr_display_removal_statistics($results, false, true);
       });
   } else {
       // Preview mode - analyze but don't delete
       $results = mepr_process_expired_members_removal(true, $batch_size, $exclude_admins);
       add_action('admin_notices', function() use ($results) {
           mepr_display_removal_statistics($results, true, false);
       });
   }
}
function mepr_process_expired_members_removal($dry_run = true, $batch_size = 100, $exclude_admins = true) {
   global $wpdb;
   $mepr_db = MeprDb::fetch();

   // Get expired member user IDs
   $sql = "
       SELECT DISTINCT m.user_id
       FROM {$mepr_db->members} AS m
       WHERE m.inactive_memberships <> ''
       AND m.inactive_memberships IS NOT NULL
       AND (m.active_txn_count <= 0 OR m.active_txn_count IS NULL)
       AND (m.trial_txn_count <= 0 OR m.trial_txn_count IS NULL)
   ";

   // Exclude administrators
   if ($exclude_admins) {
       $admin_ids = get_users(array('role' => 'administrator', 'fields' => 'ID'));
       if (!empty($admin_ids)) {
           $admin_ids_str = implode(',', array_map('intval', $admin_ids));
           $sql .= " AND m.user_id NOT IN ({$admin_ids_str})";
       }
   }

   // Exclude current user
   if (is_user_logged_in()) {
       $current_user_id = get_current_user_id();
       $sql .= " AND m.user_id != " . intval($current_user_id);
   }

   $sql .= " ORDER BY m.user_id ASC";

   // Get user IDs
   $user_ids = $wpdb->get_col($sql);
   $total = count($user_ids);

   // Initialize counters
   $deleted = 0;
   $skipped = 0;
   $errors = array();
   $skipped_users = array();
   $deleted_users = array();

   if ($total == 0) {
       return array(
           'total' => 0,
           'deleted' => 0,
           'skipped' => 0,
           'errors' => array(),
           'skipped_users' => array(),
           'deleted_users' => array()
       );
   }

   // Process members
   $processed = 0;
   foreach ($user_ids as $user_id) {
       $user = new MeprUser($user_id);

       if (!$user->ID) {
           $skipped++;
           $errors[] = "User ID {$user_id}: User not found";
           continue;
       }

       // Double-check user is not active
       if ($user->is_active()) {
           $user_data = get_userdata($user_id);
           $username = $user_data ? $user_data->user_login : 'N/A';
           $email = $user_data ? $user_data->user_email : 'N/A';
           $skipped++;
           $skipped_users[] = array(
               'id' => $user_id,
               'username' => $username,
               'email' => $email,
               'reason' => 'Still active'
           );
           continue;
       }

       // Get user info
       $user_data = get_userdata($user_id);
       $username = $user_data ? $user_data->user_login : 'N/A';
       $email = $user_data ? $user_data->user_email : 'N/A';

       if ($dry_run) {
           $deleted++;
           $deleted_users[] = array(
               'id' => $user_id,
               'username' => $username,
               'email' => $email
           );
       } else {
           try {
               $user->destroy();
               $deleted++;
               $deleted_users[] = array(
                   'id' => $user_id,
                   'username' => $username,
                   'email' => $email
               );
           } catch (Exception $e) {
               $skipped++;
               $error_msg = "User ID {$user_id}: " . $e->getMessage();
               $errors[] = $error_msg;
               $skipped_users[] = array(
                   'id' => $user_id,
                   'username' => $username,
                   'email' => $email,
                   'reason' => $e->getMessage()
               );
           }
       }

       $processed++;

       // Prevent timeout
       if ($processed % 50 == 0) {
           if (function_exists('fastcgi_finish_request')) {
               @fastcgi_finish_request();
           }
       }
   }

   return array(
       'total' => $total,
       'deleted' => $deleted,
       'skipped' => $skipped,
       'errors' => $errors,
       'skipped_users' => $skipped_users,
       'deleted_users' => $deleted_users
   );
}
function mepr_display_removal_statistics($results, $dry_run = true, $completed = false) {
   $total = $results['total'];
   $deleted = $results['deleted'];
   $skipped = $results['skipped'];
   $errors = $results['errors'];

   if ($total == 0) {
       echo '<div class="notice notice-info is-dismissible">';
       echo '<p><strong>MemberPress Expired Members Removal:</strong> No expired members found.</p>';
       echo '</div>';
       return;
   }

   $notice_class = $completed ? 'notice-success' : 'notice-warning';

   echo '<div class="notice ' . $notice_class . ' is-dismissible" style="padding: 15px;">';
   echo '<h2 style="margin-top: 0;"> MemberPress Expired Members Removal - Statistics</h2>';

   if ($completed) {
       echo '<div style="background: #d4edda; border-left: 4px solid #28a745; padding: 10px; margin: 10px 0;">';
       echo '<strong>DELETION COMPLETE</strong> - ' . number_format($deleted) . ' members have been permanently deleted.';
       echo '</div>';
   } else {
       echo '<div style="background: #fff3cd; border-left: 4px solid #ffc107; padding: 10px; margin: 10px 0;">';
       echo '<strong>PREVIEW MODE</strong> - Review the statistics below. Click "Confirm Delete" to proceed with deletion.';
       echo '</div>';
   }

   echo '<div style="background: #f8f9fa; border: 1px solid #dee2e6; border-radius: 4px; padding: 15px; margin: 15px 0;">';
   echo '<h3 style="margin-top: 0;">Summary Statistics</h3>';
   echo '<table style="width: 100%; border-collapse: collapse;">';
   echo '<tr style="background: #e9ecef;">';
   echo '<th style="padding: 10px; text-align: left; border: 1px solid #dee2e6;">Metric</th>';
   echo '<th style="padding: 10px; text-align: left; border: 1px solid #dee2e6;">Count</th>';
   echo '</tr>';
   echo '<tr><td style="padding: 10px; border: 1px solid #dee2e6;"><strong>Total Expired Members Found</strong></td>';
   echo '<td style="padding: 10px; border: 1px solid #dee2e6;"><strong style="font-size: 18px; color: #0073aa;">' . number_format($total) . '</strong></td></tr>';
   echo '<tr><td style="padding: 10px; border: 1px solid #dee2e6;"><strong>' . ($dry_run ? 'Would Delete' : 'Successfully Deleted') . '</strong></td>';
   echo '<td style="padding: 10px; border: 1px solid #dee2e6;"><strong style="font-size: 18px; color: ' . ($dry_run ? '#0073aa' : '#28a745') . ';">' . number_format($deleted) . '</strong></td></tr>';
   echo '<tr><td style="padding: 10px; border: 1px solid #dee2e6;"><strong>Skipped (Still Active or Errors)</strong></td>';
   echo '<td style="padding: 10px; border: 1px solid #dee2e6;"><strong style="font-size: 18px; color: #ffc107;">' . number_format($skipped) . '</strong></td></tr>';
   if (!empty($errors)) {
       echo '<tr><td style="padding: 10px; border: 1px solid #dee2e6;"><strong>Errors</strong></td>';
       echo '<td style="padding: 10px; border: 1px solid #dee2e6;"><strong style="font-size: 18px; color: #dc3545;">' . count($errors) . '</strong></td></tr>';
   }
   echo '</table></div>';

   if ($total > 0) {
       $delete_percentage = round(($deleted / $total) * 100, 1);
       $skip_percentage = round(($skipped / $total) * 100, 1);
       echo '<div style="background: #e7f3ff; border-left: 4px solid #0073aa; padding: 10px; margin: 10px 0;">';
       echo '<strong>Breakdown:</strong> ';
       echo $delete_percentage . '% ' . ($dry_run ? 'would be deleted' : 'deleted') . ', ';
       echo $skip_percentage . '% skipped';
       echo '</div>';
   }

   if (!empty($results['deleted_users'])) {
       echo '<details style="margin: 15px 0;">';
       echo '<summary style="cursor: pointer; font-weight: bold; padding: 10px; background: #f8f9fa; border: 1px solid #dee2e6; border-radius: 4px;">';
       echo 'View ' . ($dry_run ? 'Members That Would Be Deleted' : 'Deleted Members') . ' (' . count($results['deleted_users']) . ' total)';
       echo '</summary>';
       echo '<div style="max-height: 400px; overflow-y: auto; margin-top: 10px; padding: 10px; background: #f8f9fa; border: 1px solid #dee2e6; border-radius: 4px;">';
       echo '<table style="width: 100%; font-size: 12px;">';
       echo '<tr style="background: #e9ecef;"><th style="padding: 5px; text-align: left;">ID</th><th style="padding: 5px; text-align: left;">Username</th><th style="padding: 5px; text-align: left;">Email</th></tr>';
       $sample = array_slice($results['deleted_users'], 0, 50);
       foreach ($sample as $user) {
           echo '<tr>';
           echo '<td style="padding: 5px;">' . esc_html($user['id']) . '</td>';
           echo '<td style="padding: 5px;">' . esc_html($user['username']) . '</td>';
           echo '<td style="padding: 5px;">' . esc_html($user['email']) . '</td>';
           echo '</tr>';
       }
       if (count($results['deleted_users']) > 50) {
           echo '<tr><td colspan="3" style="padding: 5px; text-align: center; font-style: italic;">... and ' . (count($results['deleted_users']) - 50) . ' more</td></tr>';
       }
       echo '</table></div></details>';
   }

   if (!empty($errors)) {
       echo '<details style="margin: 15px 0;">';
       echo '<summary style="cursor: pointer; font-weight: bold; padding: 10px; background: #f8d7da; border: 1px solid #f5c6cb; border-radius: 4px; color: #721c24;">';
       echo 'View Errors (' . count($errors) . ')';
       echo '</summary>';
       echo '<div style="margin-top: 10px; padding: 10px; background: #f8d7da; border: 1px solid #f5c6cb; border-radius: 4px;"><ul style="margin: 0;">';
       foreach (array_slice($errors, 0, 20) as $error) {
           echo '<li>' . esc_html($error) . '</li>';
       }
       if (count($errors) > 20) {
           echo '<li><em>... and ' . (count($errors) - 20) . ' more errors</em></li>';
       }
       echo '</ul></div></details>';
   }

   if ($completed) {
       echo '<div style="background: #d1ecf1; border-left: 4px solid #0c5460; padding: 10px; margin: 15px 0;">';
       echo '<p style="margin: 0;"><strong>Deletion complete!</strong> Please remove this code from functions.php for security.</p>';
       echo '</div>';
   } else {
       $nonce = wp_create_nonce('mepr_delete_expired');
       $current_url = (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] === 'on' ? "https" : "http") . "://$_SERVER[HTTP_HOST]$_SERVER[REQUEST_URI]";
       $confirm_url = add_query_arg(array('confirm' => 'yes', 'nonce' => $nonce), $current_url);

       echo '<div style="background: #f8d7da; border-left: 4px solid #dc3545; padding: 15px; margin: 15px 0; border-radius: 4px;">';
       echo '<h3 style="margin-top: 0; color: #721c24;">Confirm Deletion</h3>';
       echo '<p style="margin: 10px 0; color: #721c24;"><strong>Warning:</strong> This action cannot be undone! Make sure a database backup exists.</p>';
       echo '<p style="margin: 10px 0;">' . number_format($deleted) . ' expired members are about to be deleted.</p>';
       echo '<div style="margin: 15px 0;">';
       echo '<a href="' . esc_url($confirm_url) . '" ';
       echo 'onclick="return confirm(\'Are you absolutely sure? This will permanently delete ' . number_format($deleted) . ' members. This cannot be undone!\\n\\nMake sure a database backup exists.\\n\\nClick OK to proceed or Cancel to abort.\');" ';
       echo 'style="display: inline-block; background: #dc3545; color: white; border: none; padding: 12px 24px; font-size: 16px; font-weight: bold; border-radius: 4px; cursor: pointer; text-decoration: none;">';
       echo 'Confirm Delete ' . number_format($deleted) . ' Members';
       echo '</a></div>';
       $cancel_url = remove_query_arg(array('remove-expired-members-snippet', 'confirm', 'nonce'));
       echo '<p style="margin: 10px 0 0 0; font-size: 12px; color: #666;">Or <a href="' . esc_url($cancel_url) . '">cancel and go back</a></p>';
       echo '</div>';
   }

   echo '</div>';
}

Once the code is added, follow these steps to run the bulk removal:

1. Log in to the WordPress admin as an administrator.
2. Navigate to the following URL in the browser address bar: https://[[YOUR-SITE-URL]]/wp-admin/?remove-expired-members-snippet
3. Review the Summary Statistics panel displayed at the top of the admin screen. This is the preview (dry run) — no data has been deleted yet.
4. Expand the Members That Would Be Deleted section to review the list of affected users.
5. If the results look correct, click the Confirm Delete button and confirm the browser prompt to proceed with the permanent deletion.
6. Wait for the process to complete. A DELETION COMPLETE confirmation message will appear when finished.
7. Remove the code snippet from functions.php or disable it in WPCode immediately after use.

2) Script Times Out Before Completing

On sites with thousands of expired members or on servers with low PHP execution time limits, the script may time out before processing all users. The snippet includes a batch processing mechanism and a FastCGI flush call every 50 records to reduce this risk, but very large datasets may still require adjustment.

How to Test/Fix:

1. Locate the CONFIGURATION section near the top of the snippet.
2. Reduce the $batch_size value from 100 to a lower number, such as 50 or 25: $batch_size = 50;
3. Save the updated code and re-run the script using the same URL parameter.
4. If timeouts persist, contact the hosting provider to temporarily increase the max_execution_time PHP setting.
5. Alternatively, run the script multiple times. The query logic re-identifies remaining expired members on each run, so partial completions are safe to repeat.

3) Active Members Appear in the Deletion Preview

In some cases, a user may appear in the expired member query results even though they have a valid active membership. This can occur when MemberPress member cache data is out of sync, or when a membership was recently renewed but the members table has not yet been updated.

How to Test/Fix:

1. The snippet includes a secondary active status check using $user->is_active() for every user identified by the query. Users confirmed as still active at this stage are automatically moved to the Skipped count and are not deleted.
2. Expand the Members That Would Be Deleted list in the preview and spot-check user accounts that appear unexpected.
3. Navigate to Dashboard > MemberPress > Members and search for the user to verify their membership status before confirming deletion.
4. If a specific user should not be deleted, note their user ID. Add a manual exclusion to the SQL query in the mepr_process_expired_members_removal function before running the confirmation step.

4) Error Messages Appear During Deletion

Errors during the deletion step are captured and displayed in a collapsible View Errors panel after the script completes. Common causes include corrupted user records, foreign key constraint issues in the database, or users with dependent data that prevents full removal via $user->destroy().

How to Test/Fix:

1. Review the error list in the View Errors panel after the script completes.
2. Note the user IDs listed in the error messages.
3. For individual users, attempt manual deletion via Dashboard > Users. Select the user and use the Delete option.
4. If database constraint errors appear, use phpMyAdmin or a WP-CLI command to investigate orphaned records tied to the affected user IDs.
5. For persistent errors, provide the specific error messages to MemberPress support for further investigation.

5) Code Must Be Removed After Use

Leaving the snippet active after the bulk removal is complete creates a security risk, as the deletion URL parameter could be triggered by any logged-in administrator visiting that URL accidentally or intentionally. This is a one-time use snippet only.

How to Test/Fix:

1. If the code was added using the WPCode plugin, navigate to Dashboard > Code Snippets, locate the snippet, and either Deactivate or Delete it immediately after the deletion is confirmed.
2. If the code was added to functions.php, open the file using Dashboard > Appearance > Theme File Editor (or via FTP/SFTP) and remove the entire snippet.
3. Verify removal by visiting the trigger URL again: https://[[YOUR-SITE-URL]]/wp-admin/?remove-expired-members-snippet. No admin notice should appear if the code has been successfully removed.

Important: This snippet permanently deletes user accounts and all associated MemberPress data. Deletion cannot be undone. Always back up the database and test on a staging environment before running on a live site.

Public Facing Documentation / Additional References

Public Facing Documentation

• How to Add Custom Code Snippets in WPCode
• WordPress User Roles in MemberPress

Developer Documentation

• How to Back Up a WordPress Site — WP Beginner
• Beginner’s Guide to WordPress Database Management with phpMyAdmin — WP Beginner
• WP-CLI: wp user delete — WordPress Developer Resources