Download the PHP package bymayo/craft-points without Composer

Points for Craft CMS

A loyalty, rewards, and gamification system for Craft. Award points for any action - signups, shares, comments, purchases - tier users into levels, and build leaderboards. Add Craft Commerce and customers can redeem their points as store credit at checkout.

Features

• Visual rule builder: E.g. When X happens, if Y is true, then award Z, max once per day
• Automatic triggers: Entries, Users, Assets - plus Commerce Orders & Subscriptions on Pro
• Conditions: Entry in section, user group, order total, contains product, and more - keep rules precise
• Limits: Once per user, Max N per period, cooldowns
• Levels: Tier users into Bronze / Silver / Gold (or your own names) with colours and badges
• Leaderboard: CP page with avatars and live filtering
• Dashboard widgets: Leaderboard and Latest Awards out of the box, with more on the way
• Order redemptions: Customers redeem points as store credit at checkout - any payment gateway (Pro + Commerce)
• Integrations: Auto-works with Formie, Freeform, and Craft Commerce when installed
• Renameable: rebrand the plugin and its currency - e.g. "VIP Club" earning "Stars", or "Rewards" earning "Credits"
• Developer APIs: Twig, GraphQL queries, and a GraphQL mutation for headless apps
• Cache-safe JS helper: Fire Manual rules from inside Blitz and {% cache %} blocks
• Granular permissions: view / create / edit / delete per resource
• Extension events: Plug in your own triggers, conditions, limits, and rewards

Contents

• Editions
• Install
• Requirements
• Integrations
• How it works
• Building your first rule
• Firing a rule from your site
• Reading points in Twig
• Levels & leaderboard
• Spending points at checkout (Pro + Commerce)
• Dashboard widgets
• Examples
• Settings
• Permissions
• GraphQL
• Twig reference
• Extending the plugin

Editions

Install

• Install with Composer via composer require bymayo/craft-points from your project directory
• Enable / Install the plugin in the Craft Control Panel under Settings > Plugins

You can also install the plugin via the Plugin Store in the Craft Admin CP by searching for Points.

Requirements

• Craft CMS 5.6+
• PHP 8.2+
• Craft Commerce 5.x (only for Pro Commerce features - orders, subscriptions, redemptions)

Integrations

Points hooks into other Craft plugins to unlock extra triggers, conditions, and rewards. Integrations activate automatically when the matching plugin is detected - nothing to configure.

Your Points → Settings → General page shows which integrations are detected on your site, so you can see at a glance what features are available. Third-party developers can plug their own triggers / conditions / limits / rewards into the rule builder via Craft events - see Extending the plugin.

How it works

Three concepts cover everything:

• Rule - a "When this happens, give this many points" sentence. e.g. "When a customer pays for an order over £50, give them 100 points, max once per day".
• Award - a single payout of a rule to a user. The amount is snapshotted at the time, so editing the rule later doesn't rewrite history.
• Level - an optional tier (Bronze / Silver / Gold) a user reaches once their balance crosses a threshold.

Defaults call everything "Points" - but you can rename. The plugin can show up in the sidebar as "Rewards" or "VIP Club", the unit can be "Coins" or "Stars". Set it all under Points → Settings → General.

Building your first rule

Go to Points → Rules → New rule.

Triggers that come with the plugin

Each non-Manual trigger awards the right person automatically: the entry's author, the order's customer, the asset's uploader, etc. Manual rules don't fire on their own - your code (a form, JS button, or GraphQL mutation) decides when, as explained in Firing a rule from your site.

Birthday trigger: needs a Date field on the user layout. Set its handle in Settings → Triggers. The trigger fires on the user's next login after their birthday - it'll only appear in the rule picker once you've configured it.

Firing a rule from your site

For "Manual" rules (no trigger), pick whichever fits your setup:

1. A regular form - server-rendered pages

Best for claim-style actions where the click itself is the qualifying event - a daily-bonus button, "mark profile complete", "activate promo", etc. Pair with a Once per user or Max 1 / day limit on the rule so the button stays safe to click.

To reverse an award, post to points/awards/remove with the same shape.

For actions that require something else to happen first (a real signup, a real share), don't use the form pattern directly - the user could click it without doing the underlying action. Either fire the rule from your own controller's PHP after the real action completes, or call Points.addAward() from the JS confirmation page.

Forms don't play nicely inside Blitz / {% cache %} blocks - the embedded CSRF token gets stale. Use the JS helper on cached pages.

2. The JS helper - for buttons & cached pages

Drop this once in your layout:

Now you have window.Points everywhere. Cache-safe - works inside Blitz, {% cache %}, anything:

Both methods return a Promise:

Both resolve to an object with these fields:

Works with React, Vue, Alpine, Stimulus, htmx - anything that can call a global function.

3. A GraphQL mutation - for headless / decoupled apps

For Next.js, Nuxt, native apps, or anything where your frontend lives outside Craft's templates:

Same security rules as the form and JS API - the user must be logged in, the rule must be Manual, and points always go to the authenticated user.

Behind the scenes (the boring but important bit)

All three options share the same safety net: login required, CSRF protected, only Manual rules, current-user-only (no userId ever gets accepted from the client), Limits enforced, and the rule's active dates honoured.

That said, the client is trusted to ask politely. Someone could open devtools and call Points.addAward('shared') without actually sharing. Keep Manual rules low-value, and use trigger-based rules (Order paid, Entry created, …) for anything worth gaming.

Server-side awards

From a module, controller, or console command:

This is the only API that can target a user other than the one currently logged in.

Reading points in Twig

Loop through someone's awards:

Levels & leaderboard

Levels are tiers your users earn by accumulating points. Create them in Points → Levels with a threshold, colour, and optional badge icon.

Leaderboard:

There's also a paginated Points → Leaderboard page in the CP and a matching dashboard widget.

Spending points at checkout

Available on Pro + Craft Commerce. Customers apply points against an order - it shows up like a coupon discount, works with any payment gateway.

What happens behind the scenes:

1. Customer applies points → the plugin validates and records the intent.
2. Commerce shows it as a discount line on the order.
3. Customer pays the reduced total via any gateway.
4. On Order::EVENT_AFTER_ORDER_PAID, the points are taken from their balance (recorded as a negative award for the audit trail).
5. On refund, points are restored according to your refund-behaviour setting.

Configure conversion rate, minimum redemption, max % of order, and refund behaviour in Settings → Commerce.

Dashboard widgets

Add via the Craft dashboard → + New widget. Both are grouped under your plugin name (e.g. Rewards - Leaderboard):

Each widget respects your renames - column headers follow whatever you set in Settings.

Examples

A few real-world rule setups to get you started.

General

Welcome bonus on signup

• Trigger: User registered · Reward: 100 points · Limit: Once per user.

Daily login bonus

• Trigger: User logged in · Reward: 10 points · Limit: Max 1 / day.

Birthday gift

• Trigger: User birthday · Reward: 250 points · Limit: Max 1 / year.

Share button (Manual)

• Trigger: Manual · Reward: 5 points · Limit: Max 1 / day per user.

Commented on a post

• Trigger: Entry created · Condition: in section "Comments" · Limit: Max 5 / day · Reward: 5 points.

Commerce (Pro)

1 point per £1 spent

• Trigger: Order paid · Reward: Percentage of order total.

First-order bonus

• Trigger: First order · Reward: 500 points.

Big spender bonus (stacks with above)

• Trigger: Order paid · Condition: Total > £100 · Reward: 200 points.

Subscriber loyalty

• Trigger: Subscription renewed · Reward: 50 points per renewal.

Don't reward coupon orders

• Trigger: Order paid · Condition: Order has coupon = No · Reward: 50 points.

Settings

Settings can be edited at Points → Settings:

Settings save to the plugin's own DB table - not Project Config. That means admins can rename things on production without the next deploy from staging overwriting their changes. Developers can still pin per-environment values in config/points.php - anything there takes precedence over the DB row:

The store currency itself isn't a setting - it tracks your Craft Commerce primary store automatically. Money helpers (toMoney, spendForUser, the Available Spend / Redeemed columns) only work when Commerce is installed.

Permissions

The plugin ships granular permissions under a Points heading on each user group's permissions page:

A few role recipes:

• Customer-success agent - View awards + View leaderboard. Can look things up, can't change anything.
• Loyalty manager - Everything except Delete * and Manage settings. Can build the programme, can't drop existing rules/levels.
• Admin - All permissions.

Frontend endpoints (form, JS, GraphQL) don't use CP permissions. They only check login + the rule is Manual.

GraphQL

Mutation for firing Manual rules from a headless app:

Twig reference

Awards are a first-class element, so you can use element queries too:

Extending the plugin

Custom triggers (and their conditions)

Need points to fire on something Points doesn't ship with - a comment, a forum post, a download, anything? Write one PHP class that wraps the Yii event you care about, return a TriggerContext describing who earned what, and you're in. The trigger then shows up in the rule builder alongside the built-ins.

If your trigger has its own purpose-built conditions (e.g. "only award when the comment is longer than 100 characters"), declare them on the trigger and they're auto-registered. WHEN + IF lives in one file.

Here's a complete example - a "Comment posted" trigger with a "Comment length" condition. Drop it anywhere in your plugin, module, or site code:

Register it in one line from your plugin or module's init():

That's everything. The trigger appears in the rule builder under "Comments", the condition shows when an admin picks it, the Yii listener is attached automatically, and matching events flow through the normal conditions → limits → reward pipeline.

Both classes above are also bundled as a single copy-paste file at examples/CustomTrigger.php - grab it, swap the namespace + Comment element reference, and you're off.

A few details worth knowing:

• TriggerContext carries userId (required), plus optional amount (for percentage rewards - e.g. an order total) and orderId (so the resulting award links back to a Commerce order). Anything else rides along in metadata.
• One trigger, many events: return multiple pairs from events() if the same conceptual trigger fires on more than one Yii event.
• isAvailable() is your kill switch - return false to hide the trigger from the rule builder while a dependency is missing (e.g. a configured field handle that doesn't exist yet).
• Labels: subject(), subjectLabel(), and actionLabel() are auto-inferred from handle() and label() - override them only if the inferred values read badly.
• Standalone conditions: if you only want to add a condition (no trigger), call Points::getInstance()->conditions->register(new MyCondition()) from your init().
• Condition UI: renderConfigUi($index, $config) returns the picker's inner HTML. $config is the saved values when active, [] otherwise — use it for value="" defaults. Return '' (the default) if the condition takes no config. Build markup with craft\helpers\Cp::selectHtml/textHtml/elementSelectHtml, or $this->renderFormTemplate('_includes/forms/checkboxSelect.twig', [...]) for templates without a PHP helper. isInline() switches block layout to a single line.
• Use register(), not the event API: Points also fires Triggers::EVENT_REGISTER_TRIGGERS and Conditions::EVENT_REGISTER_CONDITION_RULES, but those fire during Points' own init() - if your plugin loads alphabetically after points, your listener will be attached too late and your trigger/condition will silently never appear. Always use Points::getInstance()->triggers->register(...) and ->conditions->register(...) from your init() - they work regardless of load order.

Award lifecycle events

Need to react to points being awarded, or block one entirely?

Events available:

Support

If you have any issues (surely not!) then I'll aim to reply to these as soon as possible. If it's a site-breaking-oh-no-what-has-happened moment, then hit me up on the Craft CMS Discord - @bymayo.