These are the key public PHP functions available to developers working with Simple Points & Rewards, current as of version 2.0.0.

Points balance

// Get a user's current spendable balance
$balance = spar_get_user_points( $user_id );

// Get lifetime total points ever earned
$lifetime = spar_get_user_total_points_earned( $user_id );

// Add or remove points
$result = spar_update_user_points(
    $user_id,        // int    - user ID
    100,             // int    - points amount
    'add',           // string - 'add' or 'remove'
    'Custom Bonus',  // string - note shown in history
    'admin_bonus',   // string - action ID slug
    array()          // array  - optional context passed to hooks
);
// $result === array( 'status' => 'applied', 'new_balance' => 1600 )
// A balance can never drop below 0.

// Read a paginated points-history log
$history = spar_get_user_points_history( $user_id, 1, 20, array( 'type_filter' => 'add' ) );
// $history['logs'] and $history['pagination']

Levels

Levels are derived from the points a customer has earned – there is no function to set a level directly. To move a customer up or down, adjust their points with spar_update_user_points() and the level recalculates automatically.

// Get all configured levels
$levels = spar_get_all_levels();

// Get a user's current level (array, or null if none configured)
$level = spar_get_user_level( $user_id );
// Returns: [ 'id' => 'level_2', 'name' => 'Silver', 'required_points' => 1000, 'points_multiplier' => 1.25, ... ]

// Get the next level (returns null if already at the top)
$next = spar_get_user_next_level( $user_id );

// Get how many points currently count toward level advancement
$level_points = spar_get_user_level_points( $user_id );

// Progress toward the next level, 0-100 (float)
$progress = spar_get_level_progress( $user_id );

// The user's current multiplier for a given earning key
$multiplier = spar_get_user_points_multiplier( $user_id, 'order' );

// Render-ready HTML (these RETURN strings - wrap in echo)
echo spar_display_user_level_badge( $user_id, true );
echo spar_display_level_progress_bar( $user_id );

Rewards

// Get a reward definition by its ID
$reward = spar_get_reward_by_id( $reward_id );

// Check if a reward has expired (Pro)
$expired = spar_is_reward_expired( $reward );

// Programmatically redeem a reward for a user
$result = spar_process_reward_redemption( $user_id, $reward_id );

Referrals

// Get or create a user's referral code
$code = spar_get_user_referral_code( $user_id );

// Generate the full referral URL (base URL optional)
$url = spar_generate_referral_url( $user_id, home_url( '/' ) );

// Get referral stats for a user
$stats = spar_get_user_referral_stats( $user_id );
// Returns: [ 'total_clicks' => 42, 'successful_referrals' => 7, 'total_points_earned' => 700, ... ]

Checkout redemption

// Convert a points value to a monetary amount
$monetary = spar_calculate_redemption_amount( $points, $currency );

// Is a points redemption currently applied to the cart?
$blocked = spar_cart_earning_blocked_by_redemption();

// Did a completed order use points at checkout?
$blocked = spar_order_earning_blocked_by_redemption( $order );

Utilities

// Apply the configured rounding mode to a points value
$rounded = spar_round_points( 12.7 );

// Get a translated label respecting singular/plural for an amount
$label = spar_get_points_label_for_count( $points );

// Get the configured plural / singular labels directly
$plural   = spar_get_configured_points_label();
$singular = spar_get_configured_points_label_singular();