Filter Action List – Advanced Customization and Integration

Developer Documentation – WPGens Points and Rewards Plugin

For advanced customization and integration, the Points and Rewards plugin provides full support for template overrides, hooks, and filters. This section is intended for developers who want to extend or modify plugin behavior beyond the standard settings available in the admin dashboard.

Template Overrides

You can override any template by copying it to your theme directory. The plugin will look for templates in the following order:

  1. your-theme/wpgens-loyalty/template-name.php
  2. your-theme/template-name.php
  3. plugin/templates/template-name.php

Available Templates to Override

  • points-page.php – Main points and rewards page
  • points-earn.php – Points earning section
  • points-redeem.php – Points redemption section
  • points-rewards.php – Rewards history section
  • points-stats.php – Points statistics section
  • points-history.php – Points transaction history
  • myaccount-loyalty-points.php – My Account loyalty points tab
  • points-page-guest.php – Guest user points page
  • refer-a-friend.php – Referral program page

Action Hooks

Plugin Lifecycle Actions

wpgens_loyalty_activate

Fires when plugin is activated.

Parameters: None

add_action('wpgens_loyalty_activate', function() {
    // Custom setup when plugin is activated
    flush_rewrite_rules();
});

wpgens_loyalty_deactivate

Fires when plugin is deactivated.

Parameters: None

add_action('wpgens_loyalty_deactivate', function() {
    // Custom cleanup when plugin is deactivated
});

Points Management Actions

wpgens_loyalty_update_points

Fires whenever points are added or deducted.

Parameters:

  • $user_id (int)
  • $points (int)
  • $type (string)
  • $source (string)
  • $reference_id (int|null)
  • $description (string)
add_action('wpgens_loyalty_update_points', function($user_id, $points, $type, $source, $reference_id, $description) {
    if ($source === 'custom_action') {
        error_log("Points {$type} for user {$user_id}: {$points} points");
    }
});

wpgens_loyalty_points_updated

Fires after points are successfully updated.

add_action('wpgens_loyalty_points_updated', function($user_id, $new_balance, $points_delta, $type, $source) {
    update_user_meta($user_id, 'last_points_update', time());
});

wpgens_loyalty_points_expired

Fires when points expire due to inactivity.

add_action('wpgens_loyalty_points_expired', function($user_id, $current_balance, $expiration_period) {
    wp_mail(
        get_userdata($user_id)->user_email,
        'Points Expired',
        "Your {$current_balance} points have expired due to {$expiration_period} days of inactivity."
    );
});

Checkout and Redemption Actions

wpgens_loyalty_points_redeemed_at_checkout

add_action('wpgens_loyalty_points_redeemed_at_checkout', function($user_id, $points_redeemed, $discount_amount, $order_id, $order) {
    error_log("User {$user_id} redeemed {$points_redeemed} points for " . wc_price($discount_amount) . " discount on order {$order_id}");
});

wpgens_points_applied_subscription_renewal

add_action('wpgens_points_applied_subscription_renewal', function($user_id, $order_id, $points_used, $discount_amount) {
    update_user_meta($user_id, 'subscription_points_used', $points_used);
});

Cron Actions

wpgens_loyalty_daily_cron

add_action('wpgens_loyalty_daily_cron', function() {
    cleanup_old_data();
});

Filter Hooks

Template Filters

wpgens_loyalty_locate_template

add_filter('wpgens_loyalty_locate_template', function($template, $template_name) {
    if ($template_name === 'points-page.php') {
        return get_template_directory() . '/custom-points-page.php';
    }
    return $template;
}, 10, 2);

wpgens_loyalty_get_template

add_filter('wpgens_loyalty_get_template', function($template_path, $template_name, $args) {
    return $template_path;
}, 10, 3);

wpgens_loyalty_template_args

add_filter('wpgens_loyalty_template_args', function($args, $template_name) {
    if ($template_name === 'points-page.php') {
        $args['custom_data'] = 'value';
        $args['user_level'] = get_user_meta(get_current_user_id(), 'loyalty_level', true);
    }
    return $args;
}, 10, 2);

Points Calculation Filters

wpgens_loyalty_should_calculate_item_points

Control whether points should be calculated for a specific item.
Recommended for modern integrations.

add_filter('wpgens_loyalty_should_calculate_item_points', function($should_calculate, $product, $quantity) {
    if ($product->get_type() === 'composite') {
        return has_composite_parent($product) ? false : true;
    }

    if ($product->get_meta('_disable_loyalty_points') === 'yes') {
        return false;
    }

    if ($quantity > 10) {
        return false;
    }

    return $should_calculate;
}, 10, 3);

wpgens_loyalty_item_price_for_points

Override the price used for points calculation.

add_filter('wpgens_loyalty_item_price_for_points', function($price, $product, $quantity) {
    if ($product->get_type() === 'composite') {
        return $product->get_meta('_base_price', true) ?: $price;
    }

    if ($quantity >= 5) {
        return $price * 0.9; // 10% discount for bulk orders
    }

    return $price;
}, 10, 3);

wpgens_loyalty_item_points_calculated

Override the final calculated points for an item.

add_filter('wpgens_loyalty_item_points_calculated', function($final_points, $product, $quantity, $base_points) {
    if (is_user_logged_in() && wp_get_current_user()->user_registered > strtotime('-30 days')) {
        return $final_points * 2;
    }

    if (has_term('premium', 'product_cat', $product->get_id())) {
        return $final_points + 50;
    }

    return $final_points;
}, 10, 4);

wpgens_loyalty_cart_points_before_discount

add_filter('wpgens_loyalty_cart_points_before_discount', function($total_points, $cart) {
    $max_points = 1000;
    if ($total_points > $max_points) {
        return $max_points;
    }

    $cart_total = $cart->get_total('edit');
    if ($cart_total > 500) {
        return $total_points + 100;
    }

    return $total_points;
}, 10, 2);

wpgens_loyalty_order_points_before_discount

add_filter('wpgens_loyalty_order_points_before_discount', function($total_points, $order) {
    if ($order->get_payment_method() === 'cod') {
        return $total_points + 25;
    }

    return $total_points;
}, 10, 2);

Points Earning Control Filters

wpgens_loyalty_disable_earning_when_points_used

add_filter('wpgens_loyalty_disable_earning_when_points_used', function($disable_earning, $applied_coupon) {
    if (isset($applied_coupon['amount']) && $applied_coupon['amount'] > 50) {
        return true;
    }

    if (isset($applied_coupon['points']) && $applied_coupon['points'] > 100) {
        return true;
    }

    return false;
}, 10, 2);

wpgens_loyalty_should_award_review_points

add_filter('wpgens_loyalty_should_award_review_points', function($should_award, $data) {
    return $data['total_reviews'] < 3;
}, 10, 2);

wpgens_loyalty_should_allow_points_for_user

add_filter('wpgens_loyalty_should_allow_points_for_user', function($should_allow, $user_id, $source, $type, $points_delta) {
    $user = get_userdata($user_id);
    $allowed_roles = ['customer', 'premium_customer'];

    if (!$user || !array_intersect($user->roles, $allowed_roles)) {
        return false;
    }

    $is_premium_member = get_user_meta($user_id, 'premium_member', true);
    if ($is_premium_member !== 'yes') {
        return false;
    }

    return true;
}, 10, 5);

UI Control Filters

wpgens_loyalty_show_loyalty_points_tab

add_filter('wpgens_loyalty_show_loyalty_points_tab', function($show_tab, $user_id) {
    $user = get_userdata($user_id);
    return $user && in_array('premium_customer', $user->roles);
}, 10, 2);

wpgens_loyalty_show_loyalty_points_content

add_filter('wpgens_loyalty_show_loyalty_points_content', function($show_content, $user_id) {
    $is_premium_member = get_user_meta($user_id, 'premium_member', true);
    return $is_premium_member === 'yes';
}, 10, 2);

wpgens_loyalty_show_points_redemption_block

add_filter('wpgens_loyalty_show_points_redemption_block', function($show_block) {
    $user = wp_get_current_user();
    return !in_array('wholesale_customer', $user->roles);
});

wpgl_show_points_earning_box

add_filter('wpgl_show_points_earning_box', function($should_show) {
    return !wp_is_mobile();
});

System Configuration Filters

wpgens_loyalty_expiry_warning_days

add_filter('wpgens_loyalty_expiry_warning_days', function($days) {
    return 14; // Send warning 14 days before expiry
});

wpgens_loyalty_is_using_cart_checkout_block

add_filter('wpgens_loyalty_is_using_cart_checkout_block', function($value, $post) {
    return has_block('woocommerce/cart', $post);
}, 10, 2);

wpgens_loyalty_cancelled_order_statuses

add_filter('wpgens_loyalty_cancelled_order_statuses', function($statuses) {
    $statuses[] = 'refunded';
    return $statuses;
});

Advanced Usage Examples

Custom Points Integration

function award_custom_points($user_id, $points, $description) {
    do_action(
        'wpgens_loyalty_update_points',
        $user_id,
        $points,
        'add',
        'custom_action',
        null,
        $description
    );
}

add_action('quiz_completed', function($user_id, $quiz_id) {
    $points = 100;
    $description = sprintf('Completed quiz #%d', $quiz_id);
    award_custom_points($user_id, $points, $description);
});

add_action('social_media_engagement', function($user_id, $platform, $action) {
    $points = 50;
    $description = sprintf('Engaged on %s: %s', $platform, $action);
    award_custom_points($user_id, $points, $description);
});

Role-Based Access Control

function wpgens_setup_role_based_points() {
    $allowed_roles = ['customer', 'premium_customer'];

    add_filter('wpgens_loyalty_should_allow_points_for_user', function($should_allow, $user_id, $source, $type, $points_delta) use ($allowed_roles) {
        $user = get_userdata($user_id);
        return $user && array_intersect($user->roles, $allowed_roles);
    }, 10, 5);

    add_filter('wpgens_loyalty_show_loyalty_points_tab', function($show_tab, $user_id) use ($allowed_roles) {
        $user = get_userdata($user_id);
        return $user && array_intersect($user->roles, $allowed_roles);
    }, 10, 2);

    add_filter('wpgens_loyalty_show_loyalty_points_content', function($show_content, $user_id) use ($allowed_roles) {
        $user = get_userdata($user_id);
        return $user && array_intersect($user->roles, $allowed_roles);
    }, 10, 2);
}

add_action('init', 'wpgens_setup_role_based_points');

User Meta-Based Access Control

add_filter('wpgens_loyalty_should_allow_points_for_user', function($should_allow, $user_id, $source, $type, $points_delta) {
    $is_premium_member = get_user_meta($user_id, 'premium_member', true);
    return $is_premium_member === 'yes';
}, 10, 5);

add_filter('wpgens_loyalty_show_loyalty_points_tab', function($show_tab, $user_id) {
    $is_premium_member = get_user_meta($user_id, 'premium_member', true);
    return $is_premium_member === 'yes';
}, 10, 2);

add_filter('wpgens_loyalty_show_loyalty_points_content', function($show_content, $user_id) {
    $is_premium_member = get_user_meta($user_id, 'premium_member', true);
    return $is_premium_member === 'yes';
}, 10, 2);

Complex Points Calculation

add_filter('wpgens_loyalty_should_calculate_item_points', function($should_calculate, $product, $quantity) {
    if ($product->get_type() === 'composite') {
        return has_composite_parent($product) ? false : true;
    }

    if ($product->get_meta('_disable_loyalty_points') === 'yes') {
        return false;
    }

    if ($quantity > 10) {
        return false;
    }

    return $should_calculate;
}, 10, 3);

add_filter('wpgens_loyalty_cart_points_before_discount', function($total_points, $cart) {
    $max_points = 1000;
    if ($total_points > $max_points) {
        return $max_points;
    }

    $cart_total = $cart->get_total('edit');
    if ($cart_total > 500) {
        return $total_points + 100;
    }

    return $total_points;
}, 10, 2);

Common Integration Patterns

Awarding Points for Custom Events

add_action('your_plugin_custom_event', function($user_id, $event_data) {
    $points = calculate_points_from_event($event_data);
    $description = sprintf('Completed %s', $event_data['event_name']);

    do_action(
        'wpgens_loyalty_update_points',
        $user_id,
        $points,
        'add',
        'your_plugin',
        $event_data['event_id'],
        $description
    );
});

Deducting Points for Penalties

function deduct_points_penalty($user_id, $points, $reason) {
    do_action(
        'wpgens_loyalty_update_points',
        $user_id,
        $points,
        'deduct',
        'penalty',
        null,
        $reason
    );
}

This comprehensive documentation covers all available hooks and filters in the WPGens Points and Rewards plugin, providing you with the tools you need to extend and customize the plugin’s functionality.

By leveraging these hooks and filters, you can:

  • Build advanced loyalty strategies,
  • Integrate with external CRMs or marketing tools,
  • Enforce custom business rules, and
  • Control exactly how points are calculated, awarded, and redeemed.
Disable Points for Specific User Role Import or migrate points from WooCommerce Points & Rewards
Browse our plugins

Lightweight WooCommerce plugins built for speed. No bloat, no frameworks -- just clean code that works.

View all plugins