Reporting events

Learn how to report user actions and business events to the Loyalty Engine as events.

Events in the Loyalty Engine track key user actions and business activities, driving your loyalty program’s functionality. Reporting these events ensures that the Loyalty Engine can capture and respond to user interactions and business activities accurately.

Report an event

The Report an Event API endpoint allows you to report events automatically from any third-party system directly to the Loyalty Engine. This is the recommended approach for integrating external systems and for automating event tracking.

Some example use cases for integrating with our API include:

• Integrating point-of-sale (POS) systems to track purchases

• Logging user interactions from a mobile app or website

• Connecting with third-party platforms to report qualifying activities or behaviours

Manual event reporting in the Loyalty Console

Events can also be reported manually within the Loyalty Console. This method is ideal for one-off events or testing, allowing administrators to specify the:

• Event type they want to report

• User associated with the event

• Event payload to capture specific event details

To report an event manually, go to Events > Event Stream > Report Event in the Loyalty Console.

---

Intrinsic event reporting

Intrinsic event types are automatically reported by the Loyalty Engine when specific API endpoints or commands are called. For example:

• A REGISTERED_ACCOUNT event is automatically reported when a user is created using the Register a new user API endpoint.

• A PURCHASED_REWARD event is automatically reported when a user purchases a reward (invoked by the Purchase a reward API command).

As intrinsic events are automatically reported, they cannot be reported manually or via API. Instead, these events are reported by calling the relevant API endpoints that trigger these system actions.

Example: Rather than manually reporting a PURCHASED_REWARD event, simply call the Purchase a Reward endpoint, which will automatically report the PURCHASED_REWARD event when the purchase completes.

---

Public vs. private event types

Event types in the Loyalty Engine are categorized as either public or private, which affects how they are authenticated when reported via API.

---

Duplicate event detection

The Loyalty Engine employs duplicate detection for event reporting to ensure data accuracy. If an identical event (same type, subject, and payload) is reported within 60 seconds of the original event, a 409 Event Already Exists error will be returned.

If your usecase dictates that you may submit multiple identical events within 60 seconds, include an additional property in the event payload like randomId: $randomString where the string is unique for every event. This will stop the system recognising the events as duplicates. Alternatively, you could enable the random number event enhancer.

---

Event payload and schema

Event data must conform to the payload schema specified for each event type. This schema dictates the data structure that the Loyalty Engine expects when processing each event. If no schema is defined the payload may be omitted.

An optional occurredAt timestamp can also be included in your request payload, specifying the exact time the event took place. This is helpful for backdated events or delayed reporting scenarios.

---

FAQs

How do I report an instrinic event type?

Intrinsic events are triggered automatically by the Loyalty Engine when specific system actions occur, such as user registration or reward purchase. Instead of reporting these events, execute the related action through the Loyalty Engine’s API (e.g., using the Purchase a Reward endpoint for PURCHASED_REWARD).

What happens if I try to report a duplicate event?

If an identical event (same type, subject, and payload) is reported within 60 seconds, the Loyalty Engine will return a 409 Event Already Exists error. This ensures data consistency by preventing duplicate records.

How does authentication differ for public and private events?

• Public events: Authenticated using the end-user’s access token and automatically associated with the user.

• Private events: Require a secret token specific to the event type, and a defined subject must be included.

Can I report events retroactively?

Yes. Include the occurredAt timestamp in the payload to specify the actual time of the event. This feature is useful for reporting events after a delay, ensuring the event aligns with the accurate timeline.

Is it possible to report events without using the API?

Yes, events can be reported manually within the Loyalty Console. This is useful for testing or logging one-time events and allows administrators to bypass API reporting for specific use cases.

Is it possible to modify or delete an event after it has been reported?

No. If an event was reported inadvertently, and reactions occurred which need neutralising (i.e. removing points which were added), you'll need to report another event and setup an associated reactor to counterbalance the original reactions.