Actions & Filters Reference

Simple Points & Rewards provides a comprehensive set of WordPress actions and filters so developers can extend, modify, or integrate with the loyalty system. All hook names are prefixed with spar_ and are current as of version 2.0.0.

Actions #

Point transactions #

• spar_before_points_update( $user_id, $points, $action, $note, $action_id, $context ) – Fires immediately before a balance change is written. $action ist add oder remove.
• spar_after_points_update( $user_id, $new_balance, $delta, $action, $note, $action_id, $context ) – Fires immediately after a balance change.
• spar_points_added( $user_id, $points, $note, $action_id, $context ) – Fires when points are added. Also triggers the points-earned email.
• spar_points_removed( $user_id, $points, $note, $action_id, $context ) – Fires when points are removed.
• spar_points_log_inserted( $insert_id, $row ) – Fires after a row is written to the points-log table.

Order points #

• spar_before_award_order_points( $order_id, $user_id ) – Before order points are calculated and awarded.
• spar_after_award_order_points( $order_id, $user_id, $points ) – After order points are awarded.
• spar_after_deduct_order_points( $order_id, $user_id, $points_to_deduct, $order_status ) – After points are deducted for a refunded, cancelled, or failed order.

Reward redemption #

• spar_before_reward_redemption( $user_id, $reward_id ) – Before a reward is processed.
• spar_after_reward_redemption( $user_id, $reward, $result ) – After redemption completes. $result is the generated voucher code (or a context string such as product_added).
• spar_voucher_claimed( $user_id, $voucher_code, $voucher_type, $voucher_value ) – After a voucher coupon is successfully created.
• spar_reward_voucher_created( $coupon_id, $coupon_code, $user_id, $reward ) – After the WooCommerce coupon backing a reward voucher is created.
• spar_custom_reward_claimed( $user_id, $developer_id, $reward, $cost_points ) – Fires when a Custom-type reward is claimed. Use $developer_id to identify your reward (see Custom Reward Types).
• spar_reward_redemption_refunded( $user_id, $reward, $error ) – If points were refunded because a redemption failed.
• spar_points_redemption_applied( $user_id, $points, $discount, $cap, $amount, $currency ) – When a points discount is applied to the cart or checkout.

Ebenen #

• spar_user_level_changed( $user_id, $new_level, $previous_level, $total_earned ) – Fires when a customer moves to a different level (up or down). $new_level und $previous_level are level arrays.

Custom ways to earn (Pro) #

• spar_register_earn_ways – Register custom ways to earn from your code. See the PHP API: Custom Ways to Earn guide.
• spar_custom_earn_trigger( $way_id, $user_id ) – Fire this action to award a registered custom way to a user.
• spar_custom_earn_awarded( $way_id, $user_id, $points, $way ) – Fires after a custom way is successfully awarded.

E-Mails #

• spar_email_sent( $type, $sent, $email, $subject, $user_id, $action_id ) – Fires after any plugin email is dispatched. $-Typ identifies the email (e.g. Punkte_verdient, Gutschein_eingelöst, level_up).

Points delay & expiry (Pro) #

• spar_points_delayed( $pending_id, $user_id, $points, $note, $action_id, $delay, $context ) – A points award was queued for delayed release.
• spar_points_inactivity_expired( $user_id, $points ) – A customer’s balance was reset due to inactivity.
• spar_points_expiry_notice_sent( $user_id, $days_until_expiry, $expiry_timestamp ) – An expiry-reminder email was sent.

Guest customers (Pro) #

• spar_guest_points_added( $email, $points, $order_id, $insert_id ) – Points were recorded against a guest billing email.
• spar_guest_points_migrated( $user_id, $email, $total_points ) – Guest points were migrated to a registered account.

Filters #

Points calculation #

• spar_user_points( $points, $user_id ) – Filter the displayed balance for a user.
• spar_user_points_multiplier( $multiplier, $user_id, $level, $earn_type ) – Adjust the multiplier for a user’s current level.
• spar_order_points_multiplier( $multiplier, $user_id, $order_id ) – Adjust the multiplier applied to an order.
• spar_order_base_points( $base, $order, $currency ) – Modify the calculated base points for an order.
• spar_order_awarded_points( $points, $order_id, $user_id, $base_points, $fixed_points, $multiplier ) – Final points awarded for an order, after multipliers and caps.
• spar_order_points_rate( $rate, $currency_code ) – Override the earning rate for a specific currency.
• spar_order_fixed_points( $fixed_points, $order, $fixed_info ) – Adjust the fixed points component added to an order.
• spar_points_calculation_total_from_order( $total, $order, $earn_key, $prefs ) – Modify the order value used in point calculation.
• spar_points_calculation_total_from_cart( $total, $cart, $earn_key, $prefs ) – Modify the cart value used in point calculation.
• spar_pre_update_user_points( $pre, $user_id, $points, $action, $note, $action_id, $context ) – Return a non-null value to short-circuit an update (nothing is written and your value is returned).
• spar_update_user_points_args( $args ) – Modify the update arguments array before it is applied.

Ebenen #

• spar_user_level( $level, $user_id, $all_levels ) – Override the resolved current level.
• spar_user_next_level( $next, $user_id, $all_levels ) – Override the resolved next level.
• spar_level_progress( $progress, $user_id, $current_level, $next_level ) – Override the computed progress percentage (0–100).
• spar_all_levels( $all_levels, $options ) – Filter the full list of configured levels.

Rewards & vouchers #

• spar_reward_object( $reward, $reward_id, $user_id ) – Modify a reward definition before it is processed.
• spar_reward_cost_points( $cost, $reward, $user_id ) – Override the points cost of a reward for a specific user.
• spar_can_redeem_reward( $can_redeem, $user_id, $reward ) – Veto a redemption (return false to block).
• spar_reward_voucher_meta( $coupon_meta, $reward, $user_id, $coupon_id, $coupon_code ) – Customise the generated WooCommerce coupon meta.

E-Mails #

• spar_email_points_earned_subject( $subject, $context ) – Filter the points-earned email subject.
• spar_email_points_earned_body( $body, $context ) – Filter the points-earned email body.
• spar_email_skip_points_earned_for_action( $action_ids ) – Return an array of action IDs for which the earned email should be suppressed.
• spar_email_wrapped_message( $wrapped, $to, $subject, $heading, $message_html ) – Filter the fully wrapped email content.

UI & labels #

• spar_points_label( $label ) – Filter the plural “Points” label used throughout the plugin.
• spar_points_label_for_count( $label, $points, $plural, $singular, $context ) – Singular/plural label resolution for a given amount.
• spar_rewards_menu_label( $label, $items ) – Filter the “Rewards” label in the My Account menu.
• spar_rewards_visible_tabs( $visible_tabs, $user_id, $available_tabs ) – Control which tabs appear on the Rewards dashboard.
• spar_account_menu_items( $items ) – Filter the My Account menu items added by the plugin.
• spar_rewards_overview_html( $overview_html, $user_id, $points, $options ) – Replace the points-overview markup on the dashboard.
• spar_user_points_history( $result, $user_id ) – Filter the assembled points-history response.
• spar_points_history_per_page( $per_page, $user_id ) – Change how many history rows are returned per page.

Example #

// Double points on Saturdays
add_filter( 'spar_order_points_multiplier', function ( $multiplier, $user_id, $order_id ) {
    if ( 'Sat' === gmdate( 'D' ) ) {
        $multiplier *= 2;
    }
    return $multiplier;
}, 10, 3 );

// Congratulate a customer when they reach a new level
add_action( 'spar_user_level_changed', function ( $user_id, $new_level, $previous, $total_earned ) {
    // e.g. send an email or sync the tier to a CRM.
}, 10, 4 );