How to Automatically Update User Roles After Fluent Forms Payment is Complete

If you run a membership site or offer paid services through Fluent Forms, you might want to automatically upgrade user roles once payment is confirmed. This tutorial shows you how to automatically update a user’s role when their Fluent Forms transaction status changes to ‘paid’.

This is particularly useful for membership sites, course platforms, or any WordPress site where you need to grant access to premium content or features after successful payment.

Why Automate User Role Updates?

Manual role updates can be time-consuming and error-prone. Automating this process offers several benefits:

1. Instant access for paying customers
2. Reduced administrative overhead
3. Improved user experience
4. Consistent role management

Understanding Fluent Forms Payment Statuses

Before implementing the solution, it’s helpful to understand the different payment statuses that Fluent Forms tracks:

• paid – Payment completed successfully
• processing – Payment is being processed
• pending – Payment is awaiting confirmation
• failed – Payment attempt failed
• refunded – Payment was refunded
• partially-refunded – Payment was partially refunded
• cancelled – Payment was cancelled

Our code will specifically trigger when the status changes to ‘paid’, ensuring users only receive upgraded roles after successful payment.

How the Solution Works

The solution uses WordPress hooks to listen for transaction status changes in Fluent Forms. When a payment status changes to ‘paid’, the function automatically updates the user’s role to a predefined role (such as ‘subscriber’ or ‘member’).

The process follows these steps:

1. Monitor transaction status changes
2. Check if the new status is ‘paid’
3. Verify the submission contains a valid user ID
4. Confirm the user exists in the database
5. Update the user’s role to the specified role

Implementation Steps

Follow these steps to implement automatic user role updates:

Step 1: Choose Your Target Role

First, decide which role you want to assign to users after payment. Common choices include:

• subscriber – Basic access level
• member – If you have a custom membership role
• customer – For e-commerce sites
• premium_user – For premium content access

Step 2: Add the Code to Your Functions File

Add the code below to your theme’s functions.php file or use a code snippet plugin. Make sure to modify the $role variable to match your desired role.

		/**
 * Update user role to after Fluent Forms transaction status changes to 'paid'.
 *
 * Possible payment statuses:
 * - paid               (Paid)
 * - processing         (Processing)
 * - pending            (Pending)
 * - failed             (Failed)
 * - refunded           (Refunded)
 * - partially-refunded (Partial Refunded)
 * - cancelled          (Cancelled)
 *
 * @param string $new_status     The new payment status. Should be 'paid' to trigger role update.
 * @param object $submission     The form submission object.
 * @param int    $transaction_id The transaction ID.
 */
function tct_ff_update_user_role_after_paid_status( $new_status, $submission, $transaction_id ) {
	/*
	 * Set the role that you want to update to.
	 *
	 * @var string
	*/
	$role = 'subscriber';

	// Only proceed if the new status is 'paid'.
	if ( strtolower( $new_status ) !== 'paid' ) {
		return;
	}

	// Check if submission object contains user_id.
	if ( empty( $submission->user_id ) ) {
		return;
	}

	$user_id = intval( $submission->user_id );

	// Confirm user exists.
	$user = get_userdata( $user_id );
	if ( ! $user ) {
		return;
	}

	// Set user role.
	$user->set_role( $role );
}
add_action( 'fluentform/after_transaction_status_change', 'tct_ff_update_user_role_after_paid_status', 10, 3 );
					

				Copy
				
									
			
			

Code Breakdown

Let’s examine each part of this code to understand how it works:

Setting the Target Role

This variable defines which role users will receive after payment. Change ‘subscriber’ to any valid WordPress role that suits your needs.

Status Verification

This check ensures the function only runs when the payment status changes to ‘paid’. The strtolower() function handles case variations.

User ID Validation

This section verifies that the form submission is linked to a registered user. If there’s no user ID, the function stops execution.

User Existence Check

This validates that the user ID corresponds to an actual user in the WordPress database before attempting to update their role.

Role Update

Finally, this line updates the user’s role to the specified role. The set_role() method replaces the user’s existing role with the new one.

Customisation Options

Here are several ways you can customise this code for different scenarios:

1. Different Roles for Different Forms

If you have multiple forms that should assign different roles, you can modify the code to check the form ID:

2. Add Role Instead of Replace

If you want to add a role to the user’s existing roles rather than replacing them, use add_role():

3. Log Role Changes

For debugging or record-keeping purposes, you might want to log when roles are updated:

4. Send Email Notification

You can also send an email notification to the user when their role is updated:

5. Handle Refunds

You might also want to downgrade users when payments are refunded:

Testing the Implementation

After implementing the code, test it thoroughly:

1. Create a test form with payment enabled
2. Register a test user account
3. Submit the form whilst logged in as the test user
4. Complete the payment process
5. Check that the user’s role has been updated correctly

Troubleshooting

If the role update isn’t working, check these common issues:

• User not logged in – Ensure users are logged in when submitting forms
• Invalid role name – Verify the role name exists in your WordPress installation
• Payment gateway issues – Ensure your payment gateway is properly configured
• Plugin conflicts – Deactivate other plugins to test for conflicts

Conclusion

Automatically updating user roles after successful payments streamlines your membership site management and improves user experience. This code provides a solid foundation that you can customise for your specific needs.

Remember to test thoroughly before implementing on a live site, and consider adding logging functionality to track role changes for debugging purposes.