Display Customer Events and Loyalty History

This use case describes how to access a customer's events and points history via SessionM APIs. Considerable focus is on the customer's ability to review their own transaction-related events and any related points they've earned through those transactions.

Customer event history and point history are stored in two different areas of the platform: timeline services and the point audit log.

The timeline activity log presents a list of customer events gathered across multiple customer touch points. It shows customer engagement throughout the history of a customer's account, including purchases, offer activity, and campaign activity. The result is an event stream that serves as the "source of truth" when analyzing a customer record. Event streams document the date and time of each event (activity), along with the corresponding activity type. This activity log information can be used to present customer activity as a list in a web page or an application experience. Customers can review their own history with a brand.

Please note that events do have more information that can be retrieved via API, information that does not appear in the activity log for your SessionM experience. For example, tag-based information such as TTLs (Time to Live) is not available in a customer's profile view, but it is something developers can access. Please work with your SessionM team if you need to pull additional data into your event stream.

The point audit log provides a record of the point transactions associated with a specific customer and their corresponding point accounts and point sources. It shows events specifically related to a customer and their loyalty points, which is critical to showcasing loyalty point history for a customer participating in a web or in-app experience.

The latter part of the use case depicts a powerful combination of data sources. The events captured in the timeline are coupled with any corresponding data for point-related transactions. This view is constructed by customer middleware that aggregates data views into one unified experience.

Customer Journey

One helpful way of understanding this use case is to consider how it reflects the customer's experience, or journey, in the "real world."

Customer logs in to coffee retailer website to retrieve event history

Customer presented with event data about their activities, including transactions, offers, events, and campaign achievements

Customer navigates to new page on coffee retailer website and requests point data

Customer reviews purchase events along with point audit log data, such as points earned, awarded, expired or exchanged

Customer uses unified view of data to decide if they must earn or burn points with additional coffee purchases

Platform Configuration

Before implementing this use case, ensure the following have been configured:

Customers

Timeline services.

Work with SessionM team to create/update customer profile.

Validate profile model has been created via Model API.

Points

Point Account and Point Source created.

Loyalty

Program design has corresponding events configured that you want to showcase to customer. For example, purchases from reward stores show only if you have configured those events and the corresponding environment setup. Program design has corresponding events, campaign, and economy rules.

General Constraints

  • Timeline and point audit log support only one language at a time.

  • Customer has to be logged in to retrieve this data; anonymous customer behavior is not included.

  • Timeline and point audit log updates are refreshed depending on ingest method. If transactions are sent via API, transaction events are updated in real-time. If transactions are sent via batch daily, transaction events are updated daily.

  • Custom events need to be identified and configured with the SessionM team at the beginning of the implementation.

Sequence Diagram

See the overall flow for this use case below.

CUSTOMER CUSTOMER CLIENT MIDDLEWARE CLIENT MIDDLEWARE SESSIONM SESSIONM GET EVENTS TIMELINE VIEW 1 Log in to account and navigate to events history page 2 Get timeline view of events history 3 Return event history details 4 Evaluate history for display to customer 5 Display events history from timeline GET EVENTS TIMELINE AND FETCH CORRESPONDING DATA IN POINT AUDIT LOG 6 Navigate to events history page 7 Get timeine view of events history 8 Return event history details 9 Fetch point audit log 10 Return point history details 11 Evaluate points details for correspondence to events details 12 Return full or partial point audit log 13 Evaluate combined timeline and point audit data for display to customer 14 Display combined data

Tasks

This use case diagram contains multiple tasks, each one depicted in its own color-coded section. For more information, see the overview below.

  1. Get Events Timeline View (Use Case Events #1 - #5)

    Provides configurable way to get a view of customer's history in a timeline.

  2. Get Events Timeline and Fetch Corresponding Data in Point Audit Log (Use Case Events #6 - #14)

    Provides access to point-related activities in the customer's audit log; activities are associated to timeline events.

Alternative Paths

If you need to ascertain when an offer was redeemed, call POST /api/2.0/offers/user_offer_history . For more information, see the endpoint's documentation describing the InfoV2 API.

If you need to retrieve information on expired points, call POST /api/1.0/point_audit_logs/fetch_point_audit_logs. For more information, see the endpoint's documentation describing the PointAuditLogs API.

Best Practices

Cache the SessionM user ID when a customer logs in so that the user_id value is available for both API calls - either getting a new timeline view or fetching the audit log. Note that external_id can also be cached for calls to get a new timeline view.

Use query parameters to control what displays for a customer’s front end experience:

  • For timeline views, see pagination attributes such as since and count and event type filtering attributes such as event_types. These are detailed in the Endpoint Parameters section of "Retrieve Events for a Single View."

  • Also for timeline views, ensure payloads managed via the Timeline API stay within the 65,553 character limit. If a transaction payload exceeds that limit, only a partial payload is displayed on a website or application screen.

  • For audit logs, see event type query parameters, which drive front end filtering on specific events. Details can be found on modification types in the Parameters section of the fetch_point_audit_logs endpoint discussion.

Avoid showing event history on the home page of an app or web site to limit the number of API calls. Instead, display this information on a paginated activity page.

Only use the strategy above when explicit point details are anticipated; otherwise, specify either of the tasks in this use case without filtering parameters.

Configure event types to show only data fields that pertain to your program; doing so limits the implementation's use of JSON objects.

Point audit log can be called only by SessionM user ID.