Creating event types
Learn how to create custom event types in the Loyalty Engine, including naming conventions, event schema setup, and the difference between public and private events.
Create an event type
To create a new custom event type, navigate to the Event Types screen in the Loyalty Console and select the Create button. Here, you’ll define the details of the event type, including its name, description, and other key properties.
You can also create event types using the Create an event type API endpoint.
When you create an event type, you specify:
Name: A unique name for the event type, which will be referenced throughout the platform.
Description: A brief description to provide context for what the event type represents.
Public/Private Status: Decide whether the event type is public (client-side) or private (backend) based on its nature.
Schema: The structure that validates the data payload sent as part of this event type.
Event Enhancers: Optional add-ons to enrich the event payload with additional data.
Omit from User Activity: Whether to hide this event from the end-user’s activity log.
Naming & codification
The name of an event type should follow specific patterns to ensure clarity and consistency across your program. Here’s how we recommend naming different types of events:
Customer action events
These represent actions taken directly by a user during an interaction with your business. Customer action events are typically since they originate from client-side systems like websites or apps.
We recommend naming them with a past-participle verb followed by a noun (e.g., VISITED_SHOP, REDEEMED_CODE, BOUGHT_SANDWICH). This naming format reflects the user action, allowing events to be easily understood (e.g., “Anna Smith visited a shop”).
Customer proceeding events
These relate to actions involving a customer but are triggered by back-office processes rather than the customer directly. These events are usually , as they are generated by backend systems.
We recommend naming them as a noun followed by a past-participle verb (e.g., INVOICE_RAISED, REFUND_GIVEN, CARD_INVALIDATED). This conveys that something happened to the user (e.g., “Anna Smith’s invoice was raised”).
Business proceeding events
These represent actions or processes that occur within your business but don’t directly relate to a specific customer (e.g., STOCK_REPLENISHED). These are generally private events as they are handled internally.
Naming considerations
Event type names can only include letters and underscores (e.g.,
BOUGHT_SANDWICH). Avoid using numbers, spaces, or special characters.If you’re using our Loyalty Microsite or Loyalty Mobile App, the event names will be displayed to end-users in Title Case with underscores replaced by spaces (e.g., “Bought Sandwich”).
If you’re using a custom interface to display a user activity log representing a user's event stream, you can map event names however you like in your front-end, but be mindful that the event type and payload are visible in the API response and can be seen in a browser’s network tab.
Use clear, descriptive names that are easy to understand. Event types should make sense both to developers and marketers.
Be consistent. Follow the recommended naming conventions (e.g., past-participle verbs for customer action events) to keep your event names uniform across your loyalty program.
Visibility – consider how the event type names will appear in end-user interfaces, the browser's network tab and in your own system logs. Make sure they are intuitive for both users and admins.
Event authorisation: public vs private
When creating an event type, you must decide whether the event will be public or private. This distinction affects how and where the event is reported:
Public event types
Public event types are generally user-driven actions, such as clicking a button or visiting a page, and are authenticated using the end-user’s personal access token.
Usage: Automatically logs actions tied directly to the user.
Authentication: Requires the end-user’s access token in the Authorization header.
Subject: Automatically set as the authenticated user; custom subjects cannot be specified.
Private event types
Private event types track interactions that happen indirectly or from secure sources and are typically reported by backend systems or third-party platforms.
Usage: Allows businesses to log background processes, internal updates, or third-party system data.
Authentication: Requires a specific secret for the event type, included as a bearer token in the Authorization header.
Subject: Must specify a subject (e.g., user.authIdentifier or user.accountNumber), which defines the loyalty program participant tied to the event.
Event type schema
When reporting an event, the event payload contains the specific data related to that event. The schema defines what data the Loyalty Engine expects for each event type.
For example, if you’re tracking a purchase event, the schema may include fields for the transaction ID, total amount, and item SKUs. The schema ensures that the payload is valid and contains the necessary information to trigger reactions and perform other actions.
See Event type schemas for more information.
Event enhancers
Event enhancers allow you to add additional data to the event’s payload, enriching it with extra details from the Loyalty Engine. This data can then be used to create conditions or criteria for reactors.
For more information, see Event enhancers.
Omit from user activity
If you choose to omit an event type from the user’s activity, it will not appear in the end-user’s activity log on their interface if called using user authentication. However, this does not remove the event from the system; it will still be recorded in the event stream within the Loyalty Console and remain visible to administrators.
Meta-type mapping
Contact WLL Support if you want to know more about meta-type mapping.
FAQs
How should I handle event types across multiple environments (e.g., staging and production)?
Event types created in one environment (e.g., staging) will not automatically carry over to another environment (e.g., production). You’ll need to recreate or export/import event types across environments using the Loyalty Console or Rewards Configuration API respectively.
What is the difference between public and private event types?
Public event types are typically triggered by client-side interactions, while private event types are triggered by backend systems. Private event types require a specific event-type secret for submission. See Event authorisation: public vs private.
How can I retrieve the secret for a private event type?
The event-type secret for private events is generated when the event type is created. You can retrieve it via the Loyalty Console or programmatically through the Retrieve event type secret API endpoint.
Can I use the same event type for actions originating from different systems (e.g., web, mobile)?
Yes, you can report the same event type for events originating from multiple systems, but ensure that the payload schema is consistent and correctly implemented for each system. Different platforms might need to report events with slight variations in data (e.g. both in-store and online purchases may use a TRANSACTION_COMPLETED event but specify a different value in the event payload to reflect whether they were an in-store or online purchase).
Last updated
Was this helpful?