`benecaster_user_badges`

Filter Free Since v1.0.0

Filter that runs whenever a subscriber’s badge list is fetched for display or embedding, inside benecaster_get_user_badges(). Called by benecaster_render_user_badges(), BadgeChipRenderer::render_for_user(), the [benecaster_user_badge] shortcode, and the badges REST field on subscriber detail/list endpoints.

The $show_id parameter is filter-only — core badge storage is not show-scoped. A subscriber’s tier badges are the same regardless of which show they subscribed to. The parameter exists so add-ons that build per-show surfaces (forums, community integrations) can scope which badges display without changing the underlying schema.

Shape variance for tenure_auto rows (since 1.0.0): badge rows produced by TenureBadgeAppender carry two extra fields that tier and manual rows do not: user_id (int, the subscriber’s WordPress user ID) and show_id (int, the show whose token determined the tenure figure; 0 on the site-wide account page render). These fields let downstream consumers — including BadgeChipRenderer::render_chip() — fire benecaster_tenure_badge_output with meaningful arguments. Consumers that iterate the filter’s output should treat user_id and show_id as present on rows where source === 'tenure_auto' and absent on all other rows.

Parameters

Name	Type	Default	Description
`$badges`	`array`	—	Badge rows from SubscriberBadgeRepository::find_for_user()
`$user_id`	`int`	—	WordPress user ID
`$show_id`	`?int`	—	Show ID if provided to benecaster_get_user_badges(), otherwise null

Returns: array

Examples

Suppress a specific badge on a particular show

add_filter( 'benecaster_user_badges', function ( array $badges, int $user_id, ?int $show_id ): array {
    if ( $show_id !== 42 ) {
        return $badges;
    }
    return array_filter( $badges, fn( $b ) => $b['label'] !== 'Internal Tester' );
}, 10, 3 );

Append a custom badge from an external source

add_filter( 'benecaster_user_badges', function ( array $badges, int $user_id ): array {
    if ( my_is_vip( $user_id ) ) {
        $badges[] = [
            'label'               => 'VIP',
            'icon_slug'           => 'star',
            'icon_attachment_id'  => null,
            'color'               => '#c0a020',
            'source'              => 'manual',
        ];
    }
    return $badges;
}, 10, 2 );

Affects

BadgeChipRenderer::render_for_user()
[benecaster_user_badge] shortcode
badges REST field on subscriber detail/list endpoints