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.