PHP API: Custom Ways to Earn

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.

Reserved IDs (used by built-in ways, cannot be reused): Anmeldung, 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