How to Programmatically Get, Add, and Remove Points Balance

You can read, add, and remove a customer’s points balance programmatically using a small set of static PHP methods. This is useful for custom integrations, snippet plugins, WP-CLI scripts, or awarding points for actions the plugin does not track natively. Everything here applies identically to both Points and Rewards for WooCommerce and Loyalty Program for WooCommerce, since both share the same points engine.

Always change balances through update_user_points() rather than writing to the database directly. The method records the activity-log entry and keeps the balance, history, and connected integrations in sync.

Get a Customer’s Points Balance

Use WPGL_Points_Core::get_points(). It returns the raw integer balance, or a formatted string if you pass true as the second argument.

// Raw integer balance
$balance = WPGL_Points_Core::get_points( $user_id );

// Formatted string, for example "1,250 Points"
$label = WPGL_Points_Core::get_points( $user_id, true );

If you omit $user_id (or pass null), the method uses the current logged-in user. There is also a lower-level method, WPGL_Database::get_user_points( $user_id ), which always returns the raw integer balance.

Add or Remove Points

Use WPGL_Database::update_user_points(). A positive delta adds points, a negative delta removes them.

WPGL_Database::update_user_points(
    $user_id,        // int    WordPress user ID
    $points_delta,   // int    positive to add, negative to remove
    $type,           // string activity type constant
    $source,         // string source constant
    $reference_id,   // int|null optional, e.g. an order ID
    $description     // string|null optional note shown in the activity log
);

Parameter	Type	Required	Description
$user_id	int	Yes	The customer whose balance is changed.
$points_delta	int	Yes	Points to add (positive) or remove (negative).
$type	string	Yes	Activity type: EARN, DEDUCT, or EXPIRE.
$source	string	Yes	Where the change came from. Use MANUAL for custom adjustments.
$reference_id	int|null	No	Optional reference such as an order ID.
$description	string|null	No	Optional custom description for the activity log.

The method returns the new balance as an integer on success, or a WP_Error on failure.

Examples

// Add 100 points as a manual adjustment
$new_balance = WPGL_Database::update_user_points(
    $user_id,
    100,
    WPGL_Points_Activity_Type::EARN,
    WPGL_Points_Source_Type::MANUAL
);

// Remove 50 points
WPGL_Database::update_user_points(
    $user_id,
    -50,
    WPGL_Points_Activity_Type::DEDUCT,
    WPGL_Points_Source_Type::MANUAL
);

// Always check for errors
if ( is_wp_error( $new_balance ) ) {
    error_log( $new_balance->get_error_message() );
}

Type and Source Constants

Use the class constants rather than raw strings so your code stays correct across updates.

Activity types (WPGL_Points_Activity_Type)

Constant	Value	Use for
EARN	EARN	Adding points (positive delta).
DEDUCT	DEDUCT	Removing points (negative delta).
EXPIRE	EXPIRE	Removing points due to expiry.

Common sources (WPGL_Points_Source_Type)

Constant	Value	Meaning
MANUAL	MANUAL	Custom or admin adjustment. Recommended for your own code.
IMPORT	IMPORT	Points added via CSV import.
PLACE_ORDER	PLACE_ORDER	Earned from an order.
REGISTRATION	REGISTRATION	Sign-up bonus.
REFER_FRIEND	REFER_FRIEND	Referral reward.
PRODUCT_REVIEW	PRODUCT_REVIEW	Reward for leaving a review.
BIRTHDAY	BIRTHDAY	Birthday bonus.

Test Mode Behavior

When the plugin is in Test Mode, only the MANUAL and IMPORT sources are applied for any user. Other sources are restricted to administrators in test mode. This is another reason to use the MANUAL source for your own adjustments, so they always run as expected.