Automating Access by Membership Status
Once role mappings are in place, PayBru handles role changes for you. No manual work is needed when members join, upgrade, downgrade, or leave.
Lifecycle Events
PayBru listens for membership lifecycle events and updates Discord roles accordingly.
| Event | What PayBru Does |
|---|---|
| New subscription | Assigns the mapped Discord role within seconds. |
| Tier upgrade | Removes the old role (if RemoveOnTierLoss is enabled) and assigns the new one. |
| Tier downgrade | Swaps roles to match the new tier. |
| Renewal (successful payment) | Role stays in place - no action needed. |
| Payment failure | Membership moves to PastDue status. Roles are kept during a 3-day grace period. If payment is not recovered within 3 days, the membership is marked as Ended and roles are removed by the hourly expiry background service. |
| Voluntary cancellation | Roles with RemoveOnTierLoss=true are removed immediately (synchronous). No grace period. |
| Refund / chargeback | Role is revoked immediately. |
When a recurring payment fails, PayBru places the membership in a PastDue state for 3 days. During this window, the member keeps their Discord roles so they are not disrupted while the payment is retried. After 3 days without successful payment, the membership status changes to Ended and an hourly expiry background service removes the associated roles.
When a member voluntarily cancels their subscription, roles with RemoveOnTierLoss enabled are removed immediately - there is no grace period. Sticky roles (RemoveOnTierLoss=false) are not affected.
How the Sync Works
- A membership event fires on PayBru (e.g., new subscription).
- PayBru checks the role mapping for that tier.
- PayBru calls the Discord API to add or remove the role.
- The member's Discord permissions update instantly.
The entire process typically completes in under five seconds. PayBru introduces a 50ms delay between individual role assignments to stay within Discord's rate limits and avoid throttling.
Caching
PayBru maintains a 5-minute cache on Discord API calls to reduce rate limiting. This means that after a role change, the cached state may take up to 5 minutes to refresh. In practice, role assignments themselves are applied immediately - the cache applies to read operations like checking guild membership.
Expired Members
When a membership expires or is cancelled:
- Roles with RemoveOnTierLoss=true are removed.
- Sticky roles (RemoveOnTierLoss=false) remain.
- The member loses access to any channels restricted to removed roles.
- The member remains in the server - they are not kicked automatically.
If you want to redirect expired members, consider creating a public "rejoin" channel that explains how to resubscribe.
Background Sync Services
PayBru runs several background services to keep Discord roles accurate:
| Service | Interval | Purpose |
|---|---|---|
| Role sync | Every 5 minutes | Reconciles expected roles against actual Discord roles for all active members. Corrects any mismatches from missed events. |
| Member count sync | Every 30 minutes | Updates community member counts displayed on dashboards. |
| Ban sync | Every 5 minutes | Synchronizes ban lists across connected communities. |
| Health check | Every 30 minutes | Verifies bot permissions are intact and cleans up stale data. |
| Membership expiry check | Every 1 hour | Detects PastDue memberships that have exceeded the 3-day grace period and removes roles. |
The role sync runs every 5 minutes, not every 6 hours. If a member reports a missing role, it will be corrected within 5 minutes at most - or you can trigger a manual resync from the dashboard.
Bulk Sync
PayBru provides two methods for bulk reconciliation:
- SyncAllCommunityMembersRolesAsync(): syncs roles for all communities at once.
- SyncCommunityMembersRolesAsync(communityId): syncs roles for a single community.
During bulk sync, PayBru checks whether each user is actually present in the Discord guild before attempting to assign roles. Disconnected servers are skipped gracefully without causing errors for other communities.
You can trigger a manual sync from Creator Dashboard > Settings > Integrations > Discord > Resync All Members.
A manual resync on a large server (1 000+ members) may take several minutes due to the 50ms delay between role assignments to respect Discord rate limits.
Notifications
PayBru can notify you when role changes occur. Enable the Discord Sync Notifications toggle in your integration settings to receive a summary in a channel of your choice.