Register your own “ways to earn” entirely from code. You define the way once (points, frequency, caps, date window, roles, dashboard card) and award it by firing a trigger. Registered ways appear read-only in the Ways to Earn settings tab, where their rules are shown and their display order can be changed.

Register a way

Hook the spar_register_earn_ways action and call spar_register_custom_earn_way( array $args ) for each way. It returns true on success or false for invalid input.

Argument	Type	Default	Description
id	string	— (required)	Your key: lowercase letters, digits, _ or -, max 64 chars. Must not collide with a built-in way.
name	string	''	Display name on the dashboard card.
description	string	''	Short description under the name.
icon	string	'fa-solid fa-star'	Font Awesome class for the card icon.
points	int	0	Points awarded each time the way is granted.
frequency	string	'once'	once, daily, weekly, monthly, or unlimited.
max_awards	int	0	Maximum total awards per user. 0 = unlimited.
start_date	string	''	Optional Y-m-d start of the eligibility window.
start_time	string	''	Optional 24h H:i, paired with start_date.
end_date	string	''	Optional Y-m-d end of the window.
end_time	string	''	Optional 24h H:i, paired with end_date.
roles	array	array()	Role slugs allowed to earn. Empty = all roles.
enabled	bool	false	Set true to make the way active.
show_on_dashboard	bool	false	Show a card on the rewards dashboard.
show_countdown	bool	false	Live “Ends in” countdown (needs an end date).
delay	int	0	Wait this long before awarding (needs the Points Delay feature).
delay_unit	string	'days'	days or hours, paired with delay.
button_text	string	''	Card button label (button shows only with text + URL).
button_url	string	''	URL the button links to.
button_id	string	''	Optional HTML id for the button.
button_class	string	''	Optional extra CSS class(es) for the button.

Reserved IDs (used by built-in ways, cannot be reused): signup, order, order_fixed, referral, first_order, nth_order, review, birthday, daily_login, spin_wheel, buy_products.

add_action( 'spar_register_earn_ways', function () {

    spar_register_custom_earn_way( array(
        'id'                => 'flash_bonus',
        'name'              => 'Weekend Flash Bonus',
        'description'       => 'Earn 100 bonus points this weekend only.',
        'icon'              => 'fa-solid fa-bolt',
        'points'            => 100,
        'frequency'         => 'once',       // once | daily | weekly | monthly | unlimited
        'max_awards'        => 0,            // 0 = unlimited total per user
        'start_date'        => '2026-01-10', // 'Y-m-d' (optional)
        'end_date'          => '2026-01-12',
        'roles'             => array(),      // empty = all roles
        'enabled'           => true,
        'show_on_dashboard' => true,
        'show_countdown'    => true,
        'button_text'       => 'Shop now',
        'button_url'        => 'https://example.com/shop',
    ) );

} );

Award a way

Once registered, award a way to a user with the trigger action. All configured rules (frequency, caps, date window, roles) are always enforced, so it is safe to call repeatedly — nothing happens when the user is not currently eligible.

// Fire the trigger (recommended)
do_action( 'spar_custom_earn_trigger', 'flash_bonus', 42 );

// Or call directly and check the result
$awarded = spar_award_custom_earn_way( 'flash_bonus', 42 ); // bool