WordPress comes with default user roles: Administrator, EditorA user role allowed to create, edit, publish, and delete pos... More, Author, Contributor, and SubscriberA user role with minimal permissions, only allowed to manage... More. Each has its own set of capabilities.

But sometimes you need something custom. A “Premium Member” role. A “Course Student” role. A “Moderator” with very specific permissions.

The good news? You can create, assign, and bulk-update custom user roles programmatically, no pluginSoftware that adds specific features or functionality to a W... More required.

This guide shows you how.

Table of Contents

1. Creating a Custom Role
2. Getting a User’s Current Role
3. Adding vs. Changing a Role
4. Programmatically Assigning a Role (Example)
5. Bulk Changing Roles

1. Creating a Custom Role

Use the add_role() function. It takes three parameters:

• Name (unique identifier)
• Display name (human readable)
• Capabilities (array of permissions)

php

function wp_expert_create_role() {
    add_role(
        'premium_member',           // unique name
        'Premium Member',           // display name
        array(
            'read'         => true,
            'edit_posts'   => false,
            'delete_posts' => false
        )
    );
}
add_action('admin_init', 'wp_expert_create_role');

Important notes:

• Once created, the role is stored in the databaseWhere all WordPress content, settings, and user data are sto... More, it persists even if you remove the code.
• To remove a role later, use remove_role('premium_member').
• Run the creation code only once (e.g., on themeTheme A collection of files that determine a site's design, ... More activation or by visiting adminThe admin (administrator) is the highest user role with full... More after adding the code, then removing it).

2. Getting a User’s Current Role

User roles are stored in user metaMeta Information about data (e.g., post meta includes author... More. To retrieve them:

php

$user_meta = get_userdata($user_id);
$user_roles = $user_meta->roles; // returns an array

Example output: ["subscriber", "premium_member"]

3. Adding vs. Changing a Role

WordPress supports multiple roles per user. You have two options:

Method	Effect	Use Case
add_role()	Adds a role (keeps existing)	User needs extra permissions
set_role()	Replaces all roles	User has only one exclusive role

Example:

php

$user = new WP_User(123); // user ID

// Current roles: ["subscriber"]
$user->add_role('premium_member');
// Now: ["subscriber", "premium_member"]

$user->set_role('editor');
// Now: ["editor"] (previous roles removed)

When to use which:

• set_role → Users have exclusive, non-overlapping roles (e.g., member OR manager)
• add_role → Users need multiple role capabilities (e.g., editorA user role allowed to create, edit, publish, and delete pos... More + member)

4. Programmatically Assigning a Role (Real Example)

Let’s say we want to upgrade a user from “Subscriber” to “Premium Member” after their 10th login.

Step-by-step logic:

1. Track login count in user metaMeta Information about data (e.g., post meta includes author... More.
2. On each login, check if count == 10 AND user has “subscriber” role.
3. If yes, change role to “premium_member”.

The code:

php

function wp_expert_upgrade_on_login($user_login, $user) {
    // Get current login count
    $logins = get_user_meta($user->ID, 'login_count', true);
    
    if (!empty($logins)) {
        $logins++;
        
        // Check condition
        if ($logins == 10 && in_array('subscriber', $user->roles)) {
            $user->set_role('premium_member');
        }
        
        update_user_meta($user->ID, 'login_count', $logins);
    } else {
        // First login
        update_user_meta($user->ID, 'login_count', 1);
    }
}
add_action('wp_login', 'wp_expert_upgrade_on_login', 10, 2);

Other triggers you can use:

• After a user makes a purchase
• After they write X comments
• After they reach a certain membership level
• On a specific date (using WP Cron)

5. Bulk Changing Roles

To change all users from one role to another:

Quick method (SQL):

sql

UPDATE wp_usermeta 
SET meta_value = 'a:1:{i:0;s:15:"premium_member";}' 
WHERE meta_key = 'wp_capabilities' 
AND meta_value LIKE '%subscriber%';

Back up your databaseWhere all WordPress content, settings, and user data are sto... More before running raw SQL.

Better method (programmatically):

php

$users = get_users(array('role' => 'subscriber'));
foreach ($users as $user) {
    $user->set_role('premium_member');
}

For advanced bulk operations (filtering by criteria, exporting), consider a pluginSoftware that adds specific features or functionality to a W... More like Users Insights.

Final Thoughts

Custom user roles give you precise control over what each user can do on your site. No pluginSoftware that adds specific features or functionality to a W... More needed for basic creation and assignment, just a few lines of code.

Best practices:

• Create roles once (on themeTheme A collection of files that determine a site's design, ... More/plugin activation, not on every pageStatic content (e.g., "About Us," "Contact") not part of chr... More load)
• Test on a staging site first
• Always back up your databaseWhere all WordPress content, settings, and user data are sto... More before bulk operations
• Use add_role() when users need multiple capabilities; set_role() for exclusive roles

Now go build that custom membership system, premium content area, or moderation workflow you’ve been thinking about.