---
title: 'API for Developers'
url: 'https://manuals.remository.com/userpoints/developer-api'
markdown: 'https://manuals.remository.com/userpoints/developer-api.md'
date: '2026-10-11'
description: 'This page is for developers integrating UserPoints with Joomla extensions. It assumes familiarity with PHP and Joomla 4/5 extension development. UserPoints is released under the GNU/GPL licence. It started life as AlphaUserPoints in 2008 and has been fully namespaced and modernised for Joomla 4 and…'
taxonomy:
  category:
    - docs
---

[](#) [ edit this page](https://github.com/getgrav/grav-skeleton-rtfm-site/blob/develop/pages/15.developer-api/docs.md) 

# API for Developers

This page is for developers integrating UserPoints with Joomla extensions. It assumes familiarity with PHP and Joomla 4/5 extension development.

UserPoints is released under the GNU/GPL licence. It started life as AlphaUserPoints in 2008 and has been fully namespaced and modernised for Joomla 4 and 5.

## How UserPoints Works

UserPoints awards (or deducts) points when a **rule** is triggered. A rule is identified by a short string called the **rule key** — for example `up_login` or `sysplgup_buypoints`. When your code calls `UserPoints::newpoints('rule_name')`, UserPoints looks up the published rule with that name, checks frequency and eligibility, and records the transaction.

Rules are configured by the site administrator in the UserPoints backend. You define what rules exist via an XML file (described below); the administrator controls how many points each rule awards.

---

## Calling the API

UserPoints uses PSR-4 autoloading. Include the namespace and check the class exists before calling, so your code degrades gracefully on sites without UserPoints:

```php
use BlackSheepResearch\Component\UserPoints\Site\UserPoints;

if (class_exists(UserPoints::class)) {
    UserPoints::newpoints('rule_name');
}
```

This awards points to the currently logged-in user.

### Award Points to a Different User

To credit another user — for example, to award an article author when someone reads their article — obtain that user's UserPoints referral ID first:

```php
use BlackSheepResearch\Component\UserPoints\Site\UserPoints;

if (class_exists(UserPoints::class)) {
    $referreid = UserPoints::getAnyUserReferreID($authorUserID);
    if ($referreid) {
        UserPoints::newpoints('rule_name', $referreid);
    }
}
```

### Prevent Duplicate Awards

To ensure a user only earns points once for a specific action, pass a key reference. UserPoints checks for an existing record with the same key and skips the award if one exists:

```php
use BlackSheepResearch\Component\UserPoints\Site\UserPoints;

if (class_exists(UserPoints::class)) {
    $keyreference = UserPoints::buildKeyreference('rule_name', $itemId);
    UserPoints::newpoints('rule_name', '', $keyreference);
}
```

### Attach Information Data

Add a descriptive string that will appear in the activity log for reference:

```php
use BlackSheepResearch\Component\UserPoints\Site\UserPoints;

if (class_exists(UserPoints::class)) {
    $keyreference = UserPoints::buildKeyreference('rule_name', $itemId);
    UserPoints::newpoints('rule_name', '', $keyreference, 'Order #12345');
}
```

### Variable Point Amounts

When the number of points should vary per transaction (for example, proportional to a purchase total), pass the amount via the `$randompoints` parameter. Use a negative value to deduct points:

```php
use BlackSheepResearch\Component\UserPoints\Site\UserPoints;

if (class_exists(UserPoints::class)) {
    $keyreference = UserPoints::buildKeyreference('rule_name', $itemId);
    UserPoints::newpoints('rule_name', '', $keyreference, '', -1450);
}
```

### Check Whether the Operation Succeeded

Pass `true` as the `$feedback` parameter to get a boolean return value. This is useful when you need to confirm a user has enough points before allowing an action:

```php
use BlackSheepResearch\Component\UserPoints\Site\UserPoints;

if (class_exists(UserPoints::class)) {
    $keyreference = UserPoints::buildKeyreference('up_purchasewithvirtuemart', $transactionID);
    if (UserPoints::newpoints('up_purchasewithvirtuemart', '', $keyreference, 'Product AM-5245', -1290, true)) {
        // points successfully deducted — proceed with order
    }
}
```

If the user does not have enough points for a deduction, `newpoints` returns `false` and displays a notice to the user. You can allow negative balances via the **Allow Negative Account** configuration option.

### Bypass User-Level Restrictions

Pass `1` as the `$force` parameter to remove any rule restriction based on user group (guest, registered, special):

```php
UserPoints::newpoints('rule_name', '', '', '', 0, false, 1);
```

### Display a Custom Message

Pass a string as `$frontmessage` to show an additional system message to the user alongside the standard points notification:

```php
UserPoints::newpoints('rule_name', '', '', '', 0, false, 0, 'Thank you for your contribution!');
```

### Full Signature

```php
UserPoints::newpoints(
    string $plugin_function,
    string $referrerid    = '',
    string $keyreference  = '',
    string $datareference = '',
    int    $randompoints  = 0,
    bool   $feedback      = false,
    int    $force         = 0,
    string $frontmessage  = ''
);
```

---

## Defining Rules via XML

Extensions that integrate with UserPoints should ship a file called `userpoints_rule.xml` anywhere inside their extension directory. UserPoints scans the `components/`, `modules/`, and `plugins/` trees during auto-detect, so the file will be found wherever your extension lives. This file tells UserPoints what rules the extension provides. The site administrator can then trigger **Auto-detect** from the UserPoints control panel to import them automatically.

Example — the Remository integration file:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<userpoints>
    <component>com_remository</component>
    <rules>
        <rule>
            <name>Upload</name>
            <description>Give points when a new file is uploaded</description>
            <plugin_function>up_remository_up</plugin_function>
            <fixed_points>true</fixed_points>
            <category>ot</category>
            <display_message>1</display_message>
            <email_notification>1</email_notification>
        </rule>
        <rule>
            <name>Download</name>
            <description>Take points when a file is downloaded</description>
            <plugin_function>up_remository_down</plugin_function>
            <fixed_points>false</fixed_points>
            <category>ot</category>
            <display_message>1</display_message>
            <email_notification>1</email_notification>
        </rule>
    </rules>
</userpoints>
```

### Category Codes

| Code | Category |
|---|---|
| ar | Articles |
| cd | Coupons |
| co | Community |
| fo | Forums / Comments |
| li | Links |
| mu | Music |
| ot | Other |
| ph | Photos |
| po | Polls |
| pu | Purchases |
| re | Recommend / Refer a friend |
| sh | Shopping |
| su | Private |
| sy | System rules |
| us | Users |
| vi | Video |

### Method Codes

Add a `<method>` element to a rule to control how often it can fire per user:

| Value | Behaviour |
|---|---|
| 1 | Once only |
| 2 | Once per day per user |
| 3 | Once per day across all users |
| 4 | Whenever (unlimited) |
| 5 | Once per week |
| 6 | Once per month |
| 7 | Once per year |

---

## Reading User Information

### Get a User's Full Profile

```php
use BlackSheepResearch\Component\UserPoints\Site\UserPoints;

$profile = UserPoints::getUserInfo($referreid);
// or by Joomla user ID:
$profile = UserPoints::getUserInfo('', $userId);
```

Returns an object with these fields:

```
$profile->name            // full name (from Joomla users table)
$profile->username        // login username
$profile->registerDate    // Joomla registration date
$profile->lastvisitDate   // last Joomla login date
$profile->email           // email address
$profile->userid          // Joomla user ID
$profile->referreid       // UserPoints referral ID
$profile->points          // current point total
$profile->max_points      // per-user point ceiling (0 = use global setting)
$profile->nummedals       // count of medals earned
$profile->last_update     // timestamp of last points change
$profile->referraluser    // referral ID of the user who referred this user
$profile->referrees       // count of users referred by this user
$profile->blocked         // 1 if UserPoints account is suspended
$profile->avatar          // avatar filename
$profile->levelrank       // current rank ID
$profile->leveldate       // date rank was last changed
$profile->profileviews    // number of times this profile page has been viewed
$profile->published       // 1 if the UserPoints account is publicly visible
$profile->shareinfos      // whether the user shares profile information
$profile->upnid           // internal UserPoints node ID
```

### Get the Current Point Total

```php
$total = UserPoints::getCurrentTotalPoints($referreid);
// or by Joomla user ID:
$total = UserPoints::getCurrentTotalPoints('', $userId);
```

### Get a User's Referral ID

```php
$referreid = UserPoints::getAnyUserReferreID($userId);
```

### Get Profile and Users List URLs

```php
$profileUrl = UserPoints::getAupLinkToProfil($userId);
$listUrl    = UserPoints::getAupUsersURL();
```

### Get a User's Medals

```php
$medals = UserPoints::getUserMedals($referreid);
// or by Joomla user ID:
$medals = UserPoints::getUserMedals('', $userId);
```

Each item in the returned array has:

```
->id
->rank          (medal name)
->description   (reason awarded)
->image         (image filename)
```

To display medal images:

```php
use BlackSheepResearch\Component\UserPoints\Administrator\Models\Image;
foreach (UserPoints::getUserMedals('', $userId) as $medal) {
    echo Image::imageHTML($medal->image);
}
```

Note that UserPoints::getMedalsLivePath(); is deprecated and no longer returns a value;

### Get the Next Rank a User Can Achieve

```php
$nextRank = UserPoints::getNextUserRank($referreid, $userId, $currentRank);
```

Returns an object with:

```
->id
->rank          (rank name)
->description
->levelpoints   (points needed to reach this rank)
->icon
->image
```

### Get the Activity List

```php
$activities = UserPoints::getListActivity($type = 'all', $userid = 'all', $numrows = 0);
```

| Parameter | Options |
|---|---|
| `$type` | `'all'`, `'positive'`, `'negative'` |
| `$userid` | `'all'` or a Joomla user ID |
| `$numrows` | Maximum rows to return; `0` for all |

Each row contains:

```
->insert_date
->referreid
->points
->datareference
->rule_name
->plugin_function
->category
```

### Get the Installed Version

```php
$version = UserPoints::getUpVersion();
```

---

## Plugin Events

UserPoints fires the following events that your plugins can hook into:

| Event | When it fires |
|---|---|
| `onBeforeInsertUserActivityUserPoints` | Before a new activity record is created |
| `onUpdateUserPoints` | When a user's point total is being updated (fires alongside `onAfterUpdateUserPoints` for compatibility with older plugins) |
| `onAfterUpdateUserPoints` | After a user's point total is updated and notification sent |
| `onSendNotificationUserPoints` | When a notification email is triggered for a point transaction |
| `onChangeLevelUserPoints` | When a user advances to a new rank |
| `onUnlockMedalUserPoints` | When a user earns a new medal |
| `onGetNewRankUserPoints` | When a user's rank is evaluated |
| `onResetGeneralPointsUserPoints` | When a user's points are reset |
| `onBeforeDeleteUserActivityUserPoints` | Before a single activity record is deleted |
| `onAfterDeleteUserActivityUserPoints` | After a single activity record is deleted |
| `onBeforeDeleteAllUserActivitiesUserPoints` | Before all activities for a user are deleted |
| `onAfterDeleteAllUserActivitiesUserPoints` | After all activities for a user are deleted |
| `onBeforeMakeRaffleUserPoints` | Before a raffle is drawn |
| `onAfterMakeRaffleUserPoints` | After a raffle is drawn |

An example plugin showing the parameters available for each event is included in the UserPoints package at `plugins/userpoints/example/`.

 [ ](https://manuals.remository.com/userpoints/integrating-userpoints-with-other-joomla-extensions)

---

## Navigation

- Previous: [Integrating UserPoints with Other Joomla Extensions](https://manuals.remository.com/userpoints/integrating-userpoints-with-other-joomla-extensions.md)
