Actions and Events

Concept of actions and events

In the Loyalty Engine, the concepts of actions and events are crucial for capturing records of customer interactions and tailoring the loyalty program experience based on comprehensive interaction history.

Actions: Capturing Customer Interactions

Actions are the raw inputs representing customer interactions across various channels—online, mobile, or in-store. They are the specific activities performed by customers, such as:

• Enrollment: A customer signs up for your loyalty program.
• Transaction changes: Adjustments in customer transaction details.

These actions are sent in requests to our system and form the basis for creating events.

Events: Detailed Records of Actions

Events are structured records in the customer database created from actions. Think of events as micro documents that encapsulate these customer actions, complete with metadata attributes (e.g., time and location of the interaction). You can read more about event attributes below.

How Actions and Events Work Together

When a customer performs an action (e.g., registering for the loyalty program), and this interaction gets sent to Antavo via API, it triggers the creation of an event in the database. This event serves as a detailed, structured record of the action, allowing you to track and analyze customer behavior.

Event types

Built-in events

Antavo comes with predefined built-in events to facilitate a smooth integration with pre-existing business processes. These events contain all the predefined relevant metadata and work out of the box with Antavo core components and modules. They enable quick and easy tracking of basic interactions, such as daily logins, purchases made on various channels, and social activities.

Browse built-in non-internal events on this page.

Custom events

However, event definitions can be completely customized to suit your business requirements, allowing you to introduce new events specific to your business needs. For example, an interaction with the lookbook in your mobile application or adding an item to a wishlist on the website.

Learn more about creating new events in the Custom events user manual.

Event attributes

Attributes can be associated with events to store specific data points or parameters of the event. Attributes provide context or details that help configure the loyalty program logic and customize loyalty program mechanisms (e.g., ID of a customer, ID of a transaction, name of a reward, number of customer’s earned points).

Through the Custom events module, you can extend the attributes of both custom events and built-in non-internal events with additional attributes.

Events can have required attributes, which means that an event cannot be registered without valid data populated in the attribute.

Each event is registered with the following default attributes:

Event registration

There is no limit to the number of events that can be recorded.

Events are immutable, meaning that once created, they cannot be removed, altered, backdated, or reassigned to different customers*. Therefore, Antavo does not provide any API methods or other interfaces to remove events. This decision maintains the integrity of data on which the functionalities of the Loyalty Engine are built.

However, depending on the type of events, there are multiple ways to negate or adjust their effect on the customer’s point balance or tier. For example, Antavo offers an event called checkout_update which updates the list of items a customer purchased in a particular pending checkout, adding/removing items, changing quantities, or manipulating the total value of the purchase. The checkout_reject event can be created for scenarios in which customers return their whole purchase.

Some events trigger changes in the customer's data, such as the point_add and point_sub events which modify the customer's score profile attribute.

Events are permanently stored until a customer leaves the loyalty program.

*The expiration date of an event is an exception to this rule. If the loyalty program handles point expiration, the expiration date (stored in the action.expdate attribute) can change in two ways:

• manually, through the ‘Change expiration date’ button on the customer profile page
• automatically, if a dynamic expiration rule is applied (the expiration date is relative to the customer’s most recently registered action)

Event sources

Antavo can process and store events coming from various input sources.

API - Registering Events Through API Requests

Antavo’s Events API is the primary interface for registering events via API requests. Let’s consider a customer purchase scenario to see it in action, where you’ll record the purchase with a checkout event. This event is a nested JSON structure containing the attributes of the purchase and the purchased items.

Here’s what the JSON looks like:

"customer": "374397439743",
"action": "checkout",
"data" : {
    "total": "200",
    "transaction_id": "5475-4343-4343-4343-3333",
    "items" : [
        {
          "transaction_id": "5475-4343-4343-4343-3333",
          "product_id": "UFA-8888-94394-EN/38/YELLOW",
          "product_name": "Yellow T-Shirt",
          "product_url": "https://example.com/yellow-t-shirt",
          "quantity": "1",
          "subtotal": "200",
          "price": "200",
          "product_category": "t-shirts"
        }
    ]
}

• customer: The unique ID of the customer, consistently used across all interactions.
• action: The interaction registered (e.g. checkout)
• data: Depending on the type of action, additional details can be provided about the action, including transactional details and item specifics.

Requests sent to the following API endpoints can also trigger event registration:

Making the API Call

To register this event, you’ll use a POST request to the Events API. Here’s an example using cURL:

curl -X POST \\

'<https://api.>\<API_REGION>.antavo.com/events?api_key=\<API_KEY>' \\  
-H 'Content-Type: application/x-www-form-urlencoded' \\  
-H 'cache-control: no-cache' \\  
-d  
'customer=374397439743&action=checkout&data%5Btransaction_id%5D=5475-4343-4343-4343-3333&data%5Btotal%5D=200&data%5Bitems%5D%5B0%5D%5Btransaction_id%5D=5475-4343-4343-4343-3333&data%5Bitems%5D%5B0%5D%5Bquantity%5D=1&data%5Bitems%5D%5B0%5D%5Bprice%5D=200&data%5Bitems%5D%5B0%5D%5Bsubtotal%5D=200&data%5Bitems%5D%5B0%5D%5Bproduct_name%5D=Yellow%20T-Shirt&data%5Bitems%5D%5B0%5D%5Bproduct_id%5D=TUFA-8888-94394-EN%2FXL%2FYELLOW&data%5Bitems%5D%5B0%5D%5Bproduct_url%5D=https%3A%2F%2Fexample.com%2Fyellow-t-shirt&data%5Bitems%5D%5B0%5D%5Bproduct_category%5D=t-shirts'

Understanding the API Response

After making the request, you’ll receive a JSON response. This typically includes the profile of the customer involved in the event, the event’s ID, points earned, and other relevant details.

👍

Best practices and tips

• Unique Customer IDs: Ensure the customer attribute is unique and consistent for each customer. This can be managed through an ERP (Enterprise resource planning) or OMS (Order Management System), or by assigning a unique loyalty identifier.
• Security: In a production environment, ensure your API requests are securely signed.
• Events API documentation: The Events API documentation includes detailed information on error handling, request and response formats, and usage principles.

Incoming Webhook Processing

Instead of API calls, you can also use Antavo’s Incoming Webhooks module if you want your webhook messages translated into events registered on the customers' loyalty program events histories.

Detailed instructions about how to send webhooks messages to Antavo are available in the Incoming webhooks module user manual.

Imports - Processing CSV files

When dealing with a large number of events, the Imports module of the Management UI is a feasible solution. Instead of overloading APIs or webhooks, you can simply compile events into a CSV file and import them all at once. This method is especially useful for events generated by third-party systems where direct API integration isn't feasible.

🚧

Note

Checkouts cannot be processed when uploaded in CSVs, like they would be if sent via API.

Creating the CSV file

Each column in the CSV corresponds to an event attribute. Here's an example format of importing opt-in events:

_id,action,email,first_name,last_name  
374397439743,opt_in,[email protected],John,Bates
345454656512,opt_in,[email protected],Bill,Overback  
342856642764,opt_in,[email protected],Claudette,Moral

• _id: Unique ID of the event.
• action: The interaction to be recorded.
• email: Customer's email address.
• first_name: Customer's first name.
• last_name: Customer's last name.

Detailed instructions on how to use the Imports module and upload files are available in the Imports module user manual. The uploaded files are processed asynchronously and the progress can be followed on the interface provided in the Management UI.

Direct Integrations

Antavo integrates with CRM systems, marketing clouds, and other customer relationship platforms to facilitate the flow of loyalty data between distinct systems. These integrations can also generate events in Antavo, such as when a lead becomes a customer, a customer opens a newsletter, or a customer browses through a website.

Manual Event Registration

Management UI users can also manually add events one by one to the customers' event histories. This can be useful for recording unique customer interactions or correcting customer data and point balances. Manually added events include the admin attribute, which stores the ID of the user who registered the event.

Find instructions in the Customer insights user manual.

Workflows

The Workflows module lets Management UI users configure customer engagement journey flows to adjust the loyalty program mechanics or set up periodic campaigns. Workflows can generate events through the action nodes. You can find detailed instructions on how to use these workflow nodes in the Workflow Actions user manual.

📘

Note

Events can also serve as triggers of workflows and connected Event attribute filters may limit the scope of the workflow execution based on specific event attribute values. For example, a workflow can be set up to run each time a customer uses the mobile application, automatically assigning a coupon that the customer can use for mobile app purchases.

Internal Events

The core components and the modules of the Loyalty Engine generate built-in internal events assigned to customers as part of their operations. For example, the Contest lite module registers the promotion_winner event when a customer is drawn as the winner of a contest.

It's important to note that these events cannot be registered from any of the previously mentioned sources.

You can browse the list of internal events on this page.

Accessing registered customer events

A loyalty-centric view of customers’ data and recorded events is crucial.

Throughout the lifecycle of the loyalty program, data analysis can easily uncover insights into flawed business processes or poorly implemented code. Visualizing data during daily operations can reveal discrepancies and aid in cleansing them.

Customer events can be accessed in multiple ways:

• Management UI: An individual customer’s stream of events can be checked by opening their profile in the Management UI and navigating to the Events tab. This allows browsing through a paginated list of all events recorded for a customer with built-in filters and sorting options.
• Exports module: All data can be easily exported through the Exports module and processed externally if necessary. Initiate the export process by selecting the events of interest and other attribute filters, then request the export.
• Display API: The History endpoints of the Display API provide access to an individual customer’s events through an API request.

📘

Note

Please remember that customer events are immutable; once registered, events cannot be removed from the database or altered in any way.

Discover more about our data protection practices here.