---
title: "Role Management - PayBot Documentation"
description: "Master Discord role assignment, hierarchy, and automated role management for membership tiers. Configure roles for seamless subscriber access."
canonical: https://paybotapp.com/docs/role-management/
source: /docs/role-management/
---

[Home](https://paybotapp.com/) / [Docs](https://paybotapp.com/docs/) / Role Management

# Role Management

Master Discord role assignment, hierarchy requirements, and automated role management for seamless subscriber management

## Table of Contents

-   [Understanding Role Hierarchy](#role-hierarchy)
-   [Assigning Roles to Membership Tiers](#assigning-roles)
-   [Changing Membership Roles](#changing-roles)
-   [Removing Role Assignments](#removing-roles)
-   [Role Permissions & Best Practices](#role-permissions)
-   [Common Role Issues](#troubleshooting)

## Understanding Role Hierarchy

Discord's role hierarchy is crucial for PayBot to function correctly. PayBot must have the authority to assign and remove membership roles from users.

#### ⚠️ Critical Requirement

**PayBot's role must be positioned above all membership roles in your server's role hierarchy.** If PayBot cannot manage roles due to hierarchy restrictions, members won't receive their purchased benefits.

1

### Locate PayBot's Role

Go to **Server Settings > Roles** and find PayBot's role in the role list.

2

### Check Current Position

PayBot's role should appear at the top of your role list, above all membership roles you plan to use.

3

### Adjust Hierarchy

Drag PayBot's role to the top of the hierarchy, above roles like "Premium Member", "VIP", "Gold Tier", etc.

**Correct hierarchy example:**

1.  **PayBot** (highest position)
2.  Premium Member
3.  VIP Member
4.  Gold Tier
5.  @everyone (lowest position)

### Why Role Hierarchy Matters

✅

#### Can Assign Roles

When PayBot's role is above membership roles, it can freely assign and remove them from users.

❌

#### Cannot Assign Roles

When PayBot's role is below membership roles, Discord prevents role assignment due to insufficient permissions.

## Assigning Roles to Membership Tiers

Each membership tier needs a corresponding Discord role that will be automatically assigned to subscribers.

1

### Create Discord Roles First

Before creating membership tiers in PayBot, create the corresponding roles in Discord:

1.  Go to **Server Settings > Roles**
2.  Click **"Create Role"** for each membership tier
3.  Name roles clearly (e.g., "Premium Member", "VIP Access", "Gold Tier")
4.  Set appropriate colors and permissions for each role

2

### Access Role Assignment in PayBot

After creating a membership tier, assign the Discord role:

1.  In `/setup`, find your membership tier in the "Manage Pricing" section
2.  Click **"Edit"** on the tier
3.  Click **"Assign Role"** (or "Change Role" if already assigned)
4.  Select the appropriate Discord role from the dropdown menu

3

### Verify Role Assignment

Test that role assignment works correctly:

1.  Have a test account subscribe to the tier
2.  Verify the role appears in their user profile
3.  Check that they can access role-restricted channels
4.  Test cancellation to ensure role removal

#### Role Assignment Best Practices

-   **Use descriptive names:** "Premium Member" is clearer than just "Premium"
-   **Set distinct colors:** Higher tiers should have more distinctive colors
-   **Configure permissions:** Set appropriate channel and feature permissions for each role
-   **Test thoroughly:** Always test role assignment before launching to members

### Multiple Roles Per Tier

Each membership tier can assign **multiple Discord roles** at once. This is useful when subscribers need a combination of roles — for example, a "VIP" role for channel access plus a "Subscriber" role for cosmetic display.

**How it works:** In `/setup → Manage Pricing → Edit`, click **"Manage Roles"** to add or remove roles for a tier. When someone subscribes, all assigned roles are granted. When they cancel, all assigned roles are removed.

## Changing Membership Roles

You can change which Discord role is assigned to a membership tier at any time. Existing subscribers will receive the new role.

1

### Access the Tier Editor

In `/setup`, go to "Manage Pricing" and click "Edit" on the tier you want to modify.

2

### Select New Role

Click "Change Role" and select the new Discord role from the dropdown menu.

3

### Confirm Changes

Save the changes. The system will:

-   Remove the old role from existing subscribers
-   Assign the new role to existing subscribers
-   Use the new role for all future subscriptions

#### ⚠️ Impact on Existing Subscribers

When you change a tier's role:

-   **Existing subscribers** will have their old role removed and new role assigned automatically
-   **Role permissions** will change immediately for current subscribers
-   **Channel access** will update based on the new role's permissions

## Removing Role Assignments

You can remove role assignment from a membership tier, which means subscribers won't receive any Discord role when they purchase that tier.

1

### Access Role Management

In `/setup` → "Manage Pricing" → "Edit" on the desired tier.

2

### Remove Role Assignment

Click "Unassign Role" to remove the Discord role from this membership tier.

3

### Confirm Removal

Save the changes. The system will:

-   Remove the role from existing subscribers
-   Not assign any role to future subscribers
-   Keep all other tier benefits intact

### When to Remove Role Assignment

#### 🎫 Event-Based Tiers

One-time event tickets that don't need ongoing role access

#### 💰 Donation Tiers

Recognition without specific role-based permissions

#### 🔧 Temporary Access

Short-term access that doesn't require permanent roles

## Role Permissions & Best Practices

Properly configured role permissions ensure your members get the right level of access while maintaining server security.

#### Essential Permissions

-   Use slash commands - Required for /subscription command
-   View channels - Basic server access
-   Send messages - Participate in discussions
-   Read message history - See previous conversations

#### Advanced Permissions

-   Manage messages - Moderate discussions (for staff tiers)
-   Mute members - Moderation capabilities
-   Move members - Voice channel management
-   Use voice activity - Voice channel access

### Permission Strategy Tips

### 🎯 Progressive Access

Each tier should unlock additional channels and features progressively.

**Example:** Bronze → Silver → Gold → Platinum

### 🔒 Channel Categories

Organize channels into categories with role-based visibility for cleaner organization.

**Tip:** Use "Premium Access" category for exclusive content

### ⚡ Automation Benefits

Let PayBot handle all role assignments automatically - no manual work required.

**Benefit:** Instant access for subscribers, automatic cleanup on cancellation

## Common Role Issues

### ❌ Roles Not Being Assigned

#### Most Common Cause:

PayBot's role is below membership roles in the hierarchy

#### Solution:

1.  Go to **Server Settings > Roles**
2.  Drag PayBot's role above all membership roles
3.  Test with a new subscription

### ❌ Bot Lacks "Manage Roles" Permission

#### Symptoms:

-   Error messages about insufficient permissions
-   Roles not being assigned or removed

#### Solution:

1.  Go to **Server Settings > Roles**
2.  Ensure PayBot has "Manage Roles" permission
3.  Reinvite PayBot if permissions were incorrect

### ❌ Role Deleted or Renamed

#### Symptoms:

-   Subscribers not receiving roles
-   Error messages about missing roles

#### Solution:

1.  Recreate the missing Discord role
2.  Use "Change Role" in the tier editor
3.  Select the recreated role

### ❌ Subscribers Keep Old Roles

#### Possible Causes:

-   Role hierarchy issues
-   Bot temporarily offline during cancellation

#### Solution:

1.  Check role hierarchy is correct
2.  Manually remove roles if needed
3.  Contact support if issue persists

#### Audit Roles Command

Use `/audit-roles` to manually check and grant any pending subscription roles across your server. This is useful after fixing hierarchy issues or if roles weren't assigned due to a temporary problem. The command shows how many roles were granted, how many are still pending, and which users aren't in the server.

#### Need More Help?

If you're still experiencing role-related issues:

-   Check the [Troubleshooting Guide](https://paybotapp.com/docs/troubleshooting/) for detailed solutions
-   Run `/audit-roles` to fix pending role assignments
-   Contact our support team for personalized assistance

[Creating Membership Tiers](https://paybotapp.com/docs/membership-tiers/) [Managing Subscriptions](https://paybotapp.com/docs/subscription-management/)