Skip to main content

Customize tenure badges end to end — thresholds, labels, and chip markup

Premium Intermediate

Three filters shape a tenure badge, and they fire in a fixed order: milestones → label → output. Each one hands its result to the next, so they compose without interfering. This recipe runs all three in sequence — use whichever stages you need and drop the rest.

Stage 1 — benecaster_tenure_badge_milestones replaces the threshold map. Benecaster defaults to six thresholds (1, 6, 12, 24, 60, 120 months); the calculator picks the highest threshold that does not exceed the subscriber’s tenure and uses that entry’s label. Swap in your own cadence — quarterly recognition, or a single “One-Year Anniversary” marker.

The calculator sorts your map ascending and drops entries with non-positive month keys or non-string / empty labels, so return order does not matter. Returning a non-array falls back to the built-in defaults.

Stage 2 — benecaster_tenure_badge_label fires after the milestone is matched, for labels the threshold map alone cannot express: localisation, a designation for very long-tenure members, or a label for subscribers below your lowest threshold. $label is an empty string in that last case, and returning a non-empty string there is the only way to show a chip for a brand-new subscriber.

Stage 3 — benecaster_tenure_badge_output replaces the chip HTML itself, and fires only for tenure_auto rows — tier and manual badges are untouched. Use it to wrap the chip, add a tooltip, or link it somewhere.

On $show_id: per-show surfaces like the Supporter Wall pass the show being rendered. The site-wide account page passes the show of the subscriber’s earliest active token in stage 2, and 0 in stage 3. A subscriber with no active tokens at all gives 0.

Code

<?php
// Quarterly recognition — thresholds at 3 / 6 / 9 / 12 / 24 months, with
// labels that read as anniversaries rather than "N-Month Member" progression.
add_filter( 'benecaster_tenure_badge_milestones', function ( array $default ): array {
	return [
		3  => 'First-Quarter Supporter',
		6  => 'Half-Year Supporter',
		9  => 'Three-Quarter Supporter',
		12 => 'One-Year Anniversary',
		24 => 'Two-Year Anniversary',
	];
} );

// Optional: fine-tune labels once picked. `benecaster_tenure_badge_label`
// fires AFTER the milestone match with the four args below — flag long-tenure
// supporters with a distinct label the milestone map alone can't express.
add_filter( 'benecaster_tenure_badge_label', function ( string $label, int $user_id, int $show_id, int $months_since_join ): string {
	// Beyond three years, override the milestone label with a
	// custom "Charter Member" designation regardless of what the
	// milestone matcher picked. The milestone map above tops out
	// at 24 months, so this branch kicks in for month 36 onwards.
	if ( $months_since_join >= 36 ) {
		return __( 'Charter Member', 'my-addon' );
	}
	return $label;
}, 10, 4 );

// Stage 3: replace the chip markup. Fires only for `tenure_auto` rows, so
// tier badges and manually-assigned badges keep their default rendering.
// Here the chip becomes a link to a page explaining how tenure is counted.
add_filter( 'benecaster_tenure_badge_output', function ( string $html, int $user_id, int $show_id ): string {
	// $show_id is 0 on the site-wide account page (per-user mode).
	return sprintf(
		'<a href="%s" class="my-tenure-link">%s</a>',
		esc_url( home_url( '/about-membership-tenure/' ) ),
		$html
	);
}, 10, 3 );

View on GitHub →

Hooks Used

Need this built rather than just documented? See our services →