Developers: Actions and Filters

This page documents all public actions and filters available in Simple Points & Rewards (Pro) to extend behaviour or integrate with custom code.

The code provided on this page is for example only and should be used with caution and proper testing.

---

Core points lifecycle #

Filter: spar_user_points #

Modify the returned (display) balance for a user.

Parameters:

• int $points Stored balance from user meta _spar_points.
• int $user_id

Example:

add_filter( 'spar_user_points', function( $points, $user_id ) {
    // Add a virtual 100pt preview bonus for admins
    if ( user_can( $user_id, 'manage_options' ) ) {
        $points += 100;
    }
    return $points;
}, 10, 2 );

Filter: spar_update_user_points_args #

Adjust arguments before a points update is applied.

Parameters: (int $user_id, int $points, string $action, string $note, string $action_id)

Action: spar_before_points_update #

Fire before a balance update.

Parameters: (int $user_id, int $points, string $action, string $note, string $action_id)

Action: spar_after_points_update #

Fire after a balance update.

Parameters: (int $user_id, int $new_balance, int $delta, string $action, string $note, string $action_id)

Action: spar_points_added #

Back-compat hook fired when points are added.

Parameters: (int $user_id, int $points, string $note, string $action_id)

Action: spar_points_removed #

Fired when points are removed.

Parameters: (int $user_id, int $points, string $note, string $action_id)

#

Filter: spar_points_history_per_page #

Control how many log rows per page are shown in history.

Parameters: (int $per_page, int $user_id)

Filter: spar_user_points_history #

Modify the assembled history response.

Parameters: (array $result, int $user_id) where $result = [ 'logs' => [], 'pagination' => [] ].

Action: spar_user_level_changed #

Fired when a user transitions to a new level.

Parameters: (int $user_id, array $new_level, array|null $previous_level, int $lifetime_total_earned)

---

Orders (earn/deduct) #

Filters and actions for awarding or removing points during order events.

• spar_order_points_rate – Override points-per-currency-unit calculation.
• spar_order_base_points – Adjust base points before tiers/multipliers.
• spar_order_fixed_points – Adjust fixed-tier points.
• spar_order_points_multiplier – Adjust effective multiplier for the order.
• spar_order_awarded_points – Adjust final points awarded for an order.
• spar_order_points_action_text – Modify the log note for awarded order points.
• spar_before_award_order_points / spar_after_award_order_points – Before and after points awarded.
• spar_order_points_to_deduct – Adjust how many points to remove when refunded or cancelled.
• spar_order_deduction_action_id – Change the action ID used for deduction log.
• spar_order_deduction_action_text – Change log message for deduction events.
• spar_after_deduct_order_points – Fire after deducting points due to order status change.

---

Redemption & vouchers #

Hooks related to redeeming rewards, creating vouchers, and front-end redemption flow.

• spar_before_reward_redemption – Before processing a reward redemption.
• spar_reward_object – Adjust the reward array before logic.
• spar_reward_cost_points – Change how many points required.
• spar_can_redeem_reward – Allow or deny redemption.
• spar_reward_redemption_refunded – Fired when redemption fails and refunded.
• spar_after_reward_redemption – After successful redemption.
• spar_reward_voucher_meta – Modify voucher coupon meta.
• spar_reward_voucher_created – When coupon post is created.
• spar_voucher_claimed – When a voucher is claimed.

Frontend integration hooks:

• spar_before_handle_redeem_request
• spar_redeem_product_redirect_url
• spar_redeem_success_redirect
• spar_before_apply_coupon_from_query / spar_after_apply_coupon_from_query
• spar_ajax_before_apply_voucher / spar_ajax_after_apply_voucher
• spar_voucher_deferred, spar_voucher_pending_invalid, spar_voucher_auto_applied

---

Emails #

Generic email send result hook shared across all types:

Action: spar_email_sent #

Parameters: (string $type, bool $sent, string $to, string $subject, int $user_id, string $context_id)

• $type: points_earned | voucher_claimed
• $context_id: For points_earned this is $action_id; for voucher_claimed this is the voucher_code.

Filters:

• spar_email_points_earned_subject
• spar_email_points_earned_body
• spar_email_voucher_claimed_subject
• spar_email_voucher_claimed_body

---

Levels #

• spar_badge_icons
• spar_all_levels
• spar_user_level
• spar_user_next_level
• spar_level_progress
• spar_user_points_multiplier

---

My Account / Shortcode UI #

• spar_rewards_menu_label
• spar_account_menu_items — Filter final menu array after insertion.
• spar_rewards_overview_html
• spar_rewards_visible_tabs
• spar_before_rewards_tab
• spar_after_rewards_tab
• spar_render_tab_{key} — Keys: earn, claim, levels, history, vouchers.

---

Coupons (admin list) #

Filter: spar_reward_coupon_prefixes #

Adjust which coupon code prefixes are hidden from the default Coupons list table (e.g., reward vouchers, referral coupons).

Default: [ 'gift-', 'voucher-', 'ref-' ]

---

Quick Examples #

Award a flat 50 extra points on all completed orders for VIP role:

add_filter( 'spar_order_awarded_points', function( $points, $order_id, $user_id ) {
    if ( user_can( $user_id, 'vip_customer' ) ) {
        $points += 50;
    }
    return $points;
}, 10, 3 );

Require 20% fewer points to redeem any reward on Black Friday:

add_filter( 'spar_reward_cost_points', function( $cost, $reward, $user_id ) {
    if ( date( 'm-d' ) === '11-28' ) {
        $cost = (int) round( $cost * 0.8 );
    }
    return max( 1, $cost );
}, 10, 3 );

Replace claimed-voucher email subject/body:

add_filter( 'spar_email_voucher_claimed_subject', function( $subject, $ctx ) {
    return 'Your perk is live! Code: ' . $ctx['voucher_code'];
}, 10, 2 );

add_filter( 'spar_email_voucher_claimed_body', function( $body, $ctx ) {
    return wpautop( 'Use your code at checkout to save. Enjoy!' );
}, 10, 2 );

React to level ups:

add_action( 'spar_user_level_changed', function( $user_id, $new_level, $prev_level ) {
    // Tag in CRM, etc.
}, 10, 3

---

Functions #

Points management (add/remove programmatically) #

spar_update_user_points( int $user_id, int $points, string $action, string $note = '', string $action_id = 'custom' )

Update a user’s balance and insert a log row.

• $action: 'add' or 'remove'
• $note: short text placed in the points log (stored sanitised)
• $action_id: stable machine key for the event, for example order_refund, signup, review_bonus

Examples:

<?php
/**
 * Add 50 points with a clear log note and custom action key.
 */
$user_id = get_current_user_id();
if ( $user_id ) {
    $points   = absint( 50 );
    $note     = sanitize_text_field( 'Promo Bonus' );
    $action_id = sanitize_key( 'promo_bonus' );

    spar_update_user_points( $user_id, $points, 'add', $note, $action_id );
}

/**
 * Remove 30 points (e.g. manual admin adjustment).
 */
$user_id  = 123;
$points   = absint( 30 );
$note     = sanitize_text_field( 'Manual adjustment' );
$action_id = sanitize_key( 'admin_adjust' );

spar_update_user_points( $user_id, $points, 'remove', $note, $action_id );

Order points calculations (for previews/estimates) #

Helpers to calculate the same values the plugin uses when awarding order points.

Useful to show “You’ll earn X points” on product or cart pages.

spar_get_order_points_rate( string $currency_code = '' ): float

Returns points per 1.0 currency unit after settings and filters.

<?php
$rate = (float) spar_get_order_points_rate( get_woocommerce_currency() );

spar_calculate_order_base_points( WC_Order $order ): int

Spend-based points before multipliers and tiers.

<?php
$order = wc_get_order( $order_id );
$base  = (int) spar_calculate_order_base_points( $order );

spar_calculate_fixed_order_points_for_total( float $total, string $currency ): array

Fixed-tier result returns:

• points (int) current tier points
• next_delta (float|null) spend needed to reach next tier
• next_points (int|null) points gained at next tier

<?php
$total  = (float) WC()->cart->get_total( 'edit' ); // Or your own total.
$info   = spar_calculate_fixed_order_points_for_total( $total, get_woocommerce_currency() );
$current_points = (int) $info['points'];

Example: “You’ll earn X points” on product pages

<?php
add_action( 'woocommerce_single_product_summary', function() {
    if ( ! is_user_logged_in() || empty( WC()->cart ) ) {
        return;
    }

    $currency = get_woocommerce_currency();
    $rate     = (float) spar_get_order_points_rate( $currency );

    if ( $rate <= 0 ) {
        return;
    }

    global $product;

    $price    = (float) wc_get_price_excluding_tax( $product );
    $estimate = (int) floor( $price * $rate );

    if ( $estimate > 0 ) {
        echo '<p class="spar-estimate">' . esc_html(
            sprintf(
                __( 'Earn approximately %d points for this item', 'simple-points-and-rewards' ),
                $estimate
            )
        ) . '</p>';
    }
}, 25 );

Levels helper #

spar_get_user_points_multiplier( int $user_id ): float

Returns the current level-based multiplier, or 1.0 if levels are disabled.

<?php
$multiplier = function_exists( 'spar_get_user_points_multiplier' )
    ? (float) spar_get_user_points_multiplier( get_current_user_id() )
    : 1.0;

Award/deduct tied to orders (manual trigger) #

The plugin automatically awards or deducts on order events based on settings. To run awarding logic manually:

spar_award_order_points( int $order_id ): void

Idempotent if points already stored in order meta.

<?php
// Use with care; normally controlled by settings and hooks.
spar_award_order_points( (int) $order_id );

spar_deduct_refunded_order_points( int $order_id ): void

Deducts previously awarded points for refunded, cancelled, or failed orders, when enabled.

<?php
spar_deduct_refunded_order_points( (int) $order_id );

Custom Rewards #

You can create a reward of type “Custom (Developer Hook)” in the Rewards settings tab. A custom reward lets you deduct points and then run your own logic when the customer claims it.

Fields:

• Short Description – shown to customers in the Ways to Redeem list.
• Developer Reward ID – lowercase unique identifier (letters, numbers, hyphens, underscores) you can use to distinguish multiple custom rewards.

Hook fired after successful claim and points deduction:
spar_custom_reward_claimed( $user_id, $developer_id, $reward_array, $points_spent )

Example:

add_action( 'spar_custom_reward_claimed', function( $user_id, $developer_id, $reward, $points_spent ) {
  if ( 'vip_access' === $developer_id ) {
    // Grant VIP role, or set a user meta flag
    $user = get_user_by( 'ID', $user_id );
    if ( $user && ! in_array( 'vip', $user->roles, true ) ) {
      $user->add_role( 'vip' );
    }
    // Optional: notify user
    wp_mail( $user->user_email, 'VIP Access Granted', 'Enjoy your new VIP benefits!' );
  }
}, 10, 4 );

If your logic fails and you need to refund points, call:

spar_update_user_points( $user_id, $points_spent, 'add', 'Refund: custom reward failed', 'redeem_refund' );

This keeps the plugin flexible for bespoke reward types .