Custom Events

Custom Events are non-purchase behavioral signals that can trigger points campaigns, update challenge progress, and define audience conditions. They extend Loyal Guru beyond transactional loyalty to reward any action that matters to your brand.

What Is a Custom Event?

A custom event is any non-purchase interaction registered for a customer via the Streaming API. Each event is defined by a name, an event type slug, and a JSON attribute schema — making them highly flexible for any behavioral data your brand tracks.

Event	Description
App download	Customer installs or first opens the mobile app
Profile completion	Customer fills in required fields (birthday, phone)
Fitness activity	Steps tracked, km run, workout logged via wearable integration
Referral	Customer refers a friend who registers and makes a first purchase
Survey completion	Customer submits a feedback or NPS survey
Social share	Customer shares a product or campaign on social media
Partner event	Customer completes a challenge in a partner platform (e.g., running app)
Product registration	Customer registers a purchased product in a brand portal

How They Work

1. Your app or backend sends a custom event to POST /v1/custom_events with a type, customer_id, and optional payload.
2. Loyal Guru matches the event type to any active points campaigns or challenges configured for that trigger.
3. Matching rules fire and award points, wallet balance, or prizes.
4. The event is recorded in the customer's activity history.

Streaming API Endpoint

POST /v1/custom_events
{
  "customer_id": "cust_123",
  "type": "app_download",
  "occurred_at": "2026-05-13T10:00:00Z"
}

Managing Custom Events in the Owner App

Go to Customers → Events → Custom Events to create and manage custom event definitions.

Creating a Custom Event

To create a new custom event type, define three fields:

Field	Description
Name	Display name for the event (e.g., "Fitness Activity")
Event type slug	The slug/identifier used in API calls and points campaign or challenge triggers
Attributes	JSON template defining the data fields that can be passed with this event (e.g., {"km": 10, "duration_minutes": 60})

Once created, the event type appears in the Owner App and becomes available as a points campaign or challenge trigger.

Viewing Custom Events

From the Custom Events list, click on any event type to view:

• Event ID, Name, and Slug
• Attribute schema in JSON format
• Transaction log: a list of all times this event has been triggered, with per-instance details

Customer Event Tracking

Each customer's profile includes a Custom Events tab that shows a chronological log of all their interactions with each configured custom event type. This lets you quickly verify that integrations are working and that specific customers received the expected points or prizes.

Using Custom Events in Points Campaigns

When creating a points campaign, select Custom Event as the trigger and specify the event type slug. The campaign fires whenever that event type is received for an active customer.

Using Custom Events in Audiences

Custom events can be used as audience filter conditions — for example, "customers who have never triggered app_download" to target non-app users with a download incentive campaign.

Go to Campaign Personalization → Audiences → Conditions → Custom Events to add custom event filters.

note

Custom event types are configured per company. Contact your Customer Success Manager to add new event types or modify existing schemas.

Configuration

Configuration	Where
Add or configure a new event type	Customers → Events → Custom Events → New
Attach to a points campaign	Loyalty and Promotional engine → Points & Wallet → New Points Campaign → Trigger
Use in audience conditions	Campaign Personalization → Audiences → Custom Events conditions
View per-customer event history	Customers → Customers → Custom Events tab