Earning by Trigger

warning

This page covers the Legacy Rules Engine. For the new engine, see Earning Rules.

A Moment (also called a trigger or event) is an action that activates one or more loyalty rules. Multiple rules can share the same moment and fire simultaneously. Only the Fixed amount accumulation type is available for non-purchase triggers.

Trigger Types

Triggers fall into two categories: system/internal (managed within Loyal Guru) and custom (external events reported to Loyal Guru via API).

System / Internal Triggers

These triggers use predefined platform events. No external data source is needed.

Trigger	When it fires	Notes
After creating a ticket (after_create_activity)	A purchase is created via the Streaming API	Supports all accumulation types
Birthday	Evaluated daily — fires on the customer's birthday	Recommend limiting wins to once per year
Account sign-up (after_create_a_profile)	A new customer registers in the program	Automated; contact CS Manager to enable
Referral	A customer successfully refers a new customer	Both referrer and referred can receive points; contact CS Manager to enable
Manual	An admin grants points directly from the customer profile	Fixed amount only

After Purchase — Requirements

For after_create_activity to fire a rule, all of the following must be true:

• The purchase is valid (no validation errors)
• The customer exists and is active
• At least one purchase line has a positive total
• The purchase date falls within the rule's validity period

The purchase creation date (not the API request time) is used to evaluate validity dates and win limits.

Custom Triggers (Custom Events)

Custom triggers are events that originate outside Loyal Guru and are reported via the Streaming API or the Loyal Guru platform. This makes the system flexible — you can define as many custom triggers as your business needs.

Example custom triggers:

Trigger	Example reward
Daily login	5 points per daily login
Profile completion	20 points for filling out personal details
Product review	10 points per review submitted
Social media share	15 points per post shared
Store check-in	10 points per physical store visit
Anniversary bonus	200 points on membership anniversary
App review	50 points for leaving an app store review
Special promotion	Double points during a promotional period
Sports tracking	Points for submitting fitness data
Partner purchases	Points for purchases at partner locations

:::note Custom trigger limitation Custom trigger rules only support the Fixed amount accumulation type. Other accumulation models are only available for purchase-based triggers. :::

Multiple Rules on the Same Moment

All active rules attached to a moment are evaluated independently. A customer can earn from multiple rules in a single event if all conditions are satisfied — points stack.

How It Works

1. An event occurs (purchase, birthday, custom event, etc.).
2. The platform maps the event to a Moment key.
3. All active loyalty rules registered on that Moment are evaluated.
4. Rules whose victory conditions match award points to the customer.
5. Points are subject to activation delay and expiration settings configured in the rule.

Configuration

Moments are selected when creating a loyalty rule in Promotional Campaigns → Points & Wallet → Rules → Create new loyalty rule → Award value section.

Moment	Streaming API trigger
After Purchase	POST /v1/activities
Custom Event / Trigger	POST /v1/scores/trigger
Birthday	Evaluated daily by the platform
Manual	Admin action in Owner App

---

Integration: How to Fire Triggers

There are three ways to trigger point-awarding events:

1. Via Streaming API

Programmatically trigger a loyalty rule when a condition is met. Use the trigger endpoint to report a custom event:

{
  "trigger": "after_fulfill_poll",
  "country": "ES",
  "customer_id": 10,
  "loyalty_score_id": 12,
  "location_id": 1,
  "score_overwrite": 30,
  "comments": "30 extra points for completing the poll"
}

:::note Use loyalty_score_id for reliability If multiple loyalty rules are linked to the same trigger, only the first one fires (order is not guaranteed). Always specify loyalty_score_id to ensure the correct rule is triggered. :::

API reference: Streaming API — Trigger endpoint

2. Via Customer Profile (Manual Grant)

For one-off manual point grants:

1. Go to Customer Data Platform → Warehouse → Customers.
2. Find and open the customer profile.
3. On the Customer Card, click the Actions tab.
4. Click Points grant, select the loyalty rule linked to a manual trigger, and enter the points amount.

3. Via Bulk Grant (Segment or CSV)

For one-time or recurring grants to a group of customers:

By segment:

1. Go to Promotional Campaigns → Points & Wallet → Rules.
2. Find the loyalty rule (must be active, not linked to a system trigger, and award points — not rewards).
3. Click Grant points → Grant points by Segment.
4. Select a segment (max 500,000 customers) and add a comment.
5. Review the summary (total customers, total points, average per customer, estimated duration) and click Execute.

:::note Bulk grants are irreversible Review the summary carefully before executing. The action cannot be undone. Once complete, check status in Loyalty Engine → Massive Tasks History. :::

By CSV: upload a file with customer IDs and point amounts. Download the template from the Grant points screen.

4. Via Scheduled Task

For recurring automated grants to a segment:

1. Define a customer segment (e.g., "customers with 5+ purchases last week").
2. Create a Scheduled Task to run at a set recurrence (daily, weekly, monthly).
3. The task evaluates the segment and fires the appropriate loyalty rule for matching customers automatically.

This approach is useful for recurring loyalty programs tied to behavioral criteria that are not directly captured as real-time events.