Tier Badges

Tier badges are visual recognition markers that display on subscriber accounts and across your site. Each built-in membership tier can have one or more badges. Badges propagate automatically to every subscriber in that tier — you define them once per tier and Benecaster handles the rest.

Creating Badges

Go to Benecaster → Memberships → Tiers, open a tier, and click the Badges tab.

Click Add badge. Each badge has these components:

You can add multiple badges per tier. Drag to reorder — the display order on the account page and Supporter Wall follows the order set here.

Automatic Badge Grant

You don’t need to assign badges to individual subscribers manually. When you define badges for a tier, Benecaster’s BadgeReconciler automatically:

• Grants the tier’s badges to every paying subscriber with an active token for that tier
• Updates badge grants when a subscriber changes tiers (removes old tier badges, grants new ones), or when a follower is promoted to a paying subscriber
• Runs on new token generation to cover freshly-created subscriptions

Tier badges are for paying subscribers only. A follower’s free token never earns a tier’s badges, even when a membership tier happens to share the follower feed’s slug — followers are marked with a “Follower” chip instead. A follower who subscribes to a paid tier receives that tier’s badges immediately.

On first activation (or after a Benecaster update that adds badge support), a one-shot backfill runs automatically to grant badges to all existing subscribers. Following the update that limited tier badges to paying subscribers, this backfill ran once more to remove tier badges that had previously been granted to followers — manually-assigned badges were not touched. This requires no action on your part.

When a Member Cancels

By default, a member who cancels loses the tier badges they earned through that membership. If they rejoin, or their membership is reactivated, the badges come back automatically.

To let a badge outlast the membership, tick Keep after cancellation on that badge, either in its row or on the Add badge form. Members who cancel keep it. This is useful for badges that mark history rather than current standing, such as “Founding Supporter”.

• Keeping only retains a badge the member already holds. It never grants a badge to someone who did not earn it.
• Badges you assigned by hand are never removed.
• A membership suspended because your site’s Benecaster license lapsed is not a cancellation. Members keep all their badges and nothing needs restoring.
• A member who cancels but still has episodes they bought is treated as any other cancelled member. Their feed stays alive, but badges follow the membership, not the feed: they earn no new tier badges, badges marked Keep after cancellation stay, and the rest are removed.
• Turning Keep after cancellation off removes that badge from cancelled members who still hold it. Turning it on protects holders from then on but cannot bring back badges already removed.

Manual Badge Assignment

Badges can also be assigned to individual subscribers outside of the tier system. This is useful for recognition that crosses tier boundaries — for example, a “Founding Member” badge for early supporters who later upgraded or downgraded.

To assign a badge manually:

1. Go to Benecaster → Subscribers and open the subscriber’s detail panel
2. Click Add badge in the Badges section
3. Either select an existing tier badge definition (copies its label, icon, and color) or enter an ad-hoc label, icon, and color

Manual badges:

• Persist independently of the subscriber’s tier — a tier change does not remove manually-assigned badges
• Can be removed by clicking the trash icon next to the badge in the subscriber detail panel
• Tier-auto badges (those granted from a tier definition) show a “Tier” label and cannot be removed from the admin — change the subscriber’s tier instead

Where Badges Display

• Subscriber account page — chips render below the avatar, in a .benecaster-account__badges container (only when avatars are enabled)
• Admin Subscribers list — chips render below the tier label in the tier column
• Supporter Wall — displayed on each subscriber’s card when the wall is active
• Theme and plugin integrations — via the [benecaster_user_badge] shortcode or the benecaster_render_user_badges() function

The [benecaster_user_badge] Shortcode

Place badges anywhere on your site with this shortcode:

[benecaster_user_badge user_id="N" show_id="M"]

The shortcode outputs:

<span class="benecaster-user-badges">
  <span class="benecaster-badge-chip"><!-- icon + label --></span>
</span>

Returns an empty string when no user is resolved or the user has no badges.

Badge Chip CSS

A default stylesheet (assets/css/badges.css) ships with the plugin and is auto-enqueued whenever badge chips render (on the account page or via the shortcode). It creates pill-shaped chips with an icon on the left, text label on the right, and an accent-color background.

Three CSS custom properties let you override the chip appearance in your theme:

:root {
  --benecaster-badge-bg: /* overrides the accent color */;
  --benecaster-badge-text: /* overrides the text color */;
  --benecaster-badge-radius: /* overrides the border-radius (default: 999px) */;
}

The per-chip --benecaster-badge-bg is also set inline on each chip element using the badge’s defined accent color — your CSS override takes precedence over the inline style if you use the !important keyword or higher specificity.

For Developers

• benecaster_user_badges( array $badges, int $user_id, ?int $show_id ) — filter that runs whenever the badge list is fetched. Add, remove, or reorder badges per-show context.
• benecaster_get_user_badges( int $user_id = 0, ?int $show_id = null ) — public function to fetch a user’s badges programmatically.
• benecaster_user_badge_shortcode_output( string $html, array $badges, int $user_id, ?int $show_id ) — filter the raw chip HTML from the [benecaster_user_badge] shortcode.
• benecaster_badge_icons( array $icons ) — filter to add custom icons to the per-tier badge picker and the GET /badge-icons REST endpoint.
• benecaster_badge_definition_created, benecaster_badge_definition_updated, benecaster_badge_definition_deleted — actions that fire after badge definition CRUD.
• benecaster_subscriber_badge_assigned( int $grant_id, int $user_id, ?int $definition_id, int $granted_by ) and benecaster_subscriber_badge_removed( int $grant_id, int $user_id ) — fire when admins manually assign or remove badges.

See BadgeReconciler, SubscriberBadgeRepository, and BadgeChipRenderer for the class references.