Actions & Filters Reference

Simple Points and RewardsUpdated October 26, 2026

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 is add or 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.

Levels

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 and $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.

Emails

spar_email_sent( $type, $sent, $email, $subject, $user_id, $action_id ) – Fires after any plugin email is dispatched. $type identifies the email (e.g. points_earned, voucher_claimed, 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.

Levels

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.

Emails

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.

REST API, webhooks and AI filters (3.1.0)

Filter	What it changes
`spar_api_rate_limit`	Requests per minute for the REST API. Default 120 for signed-in callers, 30 for anonymous ones.
`spar_api_max_auth_failures`	Failed API key sign-ins allowed per IP address in 15 minutes. Default 20.
`spar_api_require_https`	Whether API keys need HTTPS. Default true outside local and development sites.
`spar_api_customer`	The customer data returned by the API.
`spar_api_reward`	The reward data returned by the API.
`spar_api_claimable_reward_types`	Reward types that can be claimed through the API. Default voucher, custom and store_credit.
`spar_api_openapi_public`	Whether the OpenAPI description is public. Default true.
`spar_api_openapi_spec`	The OpenAPI document before it is returned.
`spar_api_webhook_events`	The list of webhook events.
`spar_api_webhook_should_queue`	Whether a webhook delivery is queued for an event.
`spar_api_webhook_payload`	The JSON payload of a webhook delivery.
`spar_api_webhook_require_https`	Whether webhook URLs need HTTPS.
`spar_api_webhook_max_attempts`	Delivery attempts, including the first. Default 5.
`spar_api_webhook_max_failures`	Failures in a row before a webhook is switched off. Default 25.
`spar_api_webhook_disable_after`	How long a webhook must have been failing before it is switched off, in seconds. Default one day.
`spar_abilities_definitions`	The list of AI abilities.
`spar_abilities_rate_limit`	AI ability calls per user per minute. Default 120 reads and 20 writes.
`spar_abilities_log_size`	How many calls Recent AI activity keeps. Default 30.
`spar_abilities_mcp_server_enabled`	Whether the plugin’s own MCP server is created. Default true.
`spar_abilities_show_notice`	Whether the “Enable AI tools” admin notice is shown.

Hooks added in 2.3.0 and 3.0.0

Hook	Type	What it does
`spar_program_enabled`	Filter	Whether the rewards program is on. Receives `$enabled`.
`spar_program_disabled_allowed_action_ids`	Filter	Point actions that still add points while the program is off, such as admin adjustments and migrations.
`spar_program_disabled_hidden_shortcodes`	Filter	Shortcodes that show nothing while the program is off.
`spar_program_disabled_points_blocked`	Action	Fires when points are not added because the program is off. Receives `$user_id, $points, $note, $action_id, $context`.
`spar_redemption_amount_rounding`	Filter	How the points discount is rounded: `round` (default), `floor` or `ceil`. Receives `$mode, $currency`.
`spar_points_discount_includes_tax`	Filter	Whether the points discount includes tax.
`spar_refunds_allow_negative_balance`	Filter	Whether refunds can take the balance below zero.
`spar_deduct_referral_points_on_partial_refund`	Filter	Whether partial refunds take back part of a percentage referral bonus.
`spar_hide_earning_message_on_page`	Filter	Whether to hide the “You will earn” message. Receives `$hidden, $page`, where `$page` is cart, checkout or thankyou.
`spar_campaign_banners_html`	Filter	The campaign banner HTML (Pro). Receives `$html, $location`.
`spar_earn_tab_layout`	Filter	The Earn Points tab layout: `cards` or `list`.
`spar_order_points_adjusted`	Action	Fires after Adjust points changes an order’s points. Receives `$order_id, $user_id, $old, $new, $reason, $result`.
`spar_csv_import_column_aliases`	Filter	Column headings accepted by the CSV import.
`spar_csv_import_max_size`	Filter	The largest CSV file accepted, in bytes. Default 20 MB.
`spar_admin_tools`	Filter	The cards on the Tools page.
`spar_dashboard_cache_ttl`	Filter	How long the Dashboard figures are cached, in seconds. Default 600.
`spar_store_credit_active`	Filter	Whether the Simple Store Credit integration is active.
`spar_points_converted_to_store_credit`	Action	Fires after a customer converts points to store credit. Receives `$user_id, $points, $awarded`.
`spar_store_credit_reward_claimed`	Action	Fires after a Store Credit reward is claimed. Receives `$user_id, $reward, $awarded`.

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 );