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 three 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 subscriber with an active token for that tier
• Updates badge grants when a subscriber changes tiers (removes old tier badges, grants new ones)
• Runs on new token generation to cover freshly-created subscriptions

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. This requires no action on your part.

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 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.