Get Events Timeline and Fetch Corresponding Data in Point Audit Log

First, gets an events timeline view, and then fetches specific data in the point audit log that corresponds with the timeline events. This two-step process describes a powerful way to retrieve data on customer events from two sources: the timeline and the point audit log. The enhanced data available in the point audit log expands on the more basic data related to a customer's event history. Access to its data is particularly useful when you need to show explicit point details, including point expiration, points earned from a specific transaction ID, and points spent for a specific reward store item.

Sequence Diagram

See the overall flow for this task below.

CUSTOMER CUSTOMER CLIENT MIDDLEWARE CLIENT MIDDLEWARE SESSIONM SESSIONM GET EVENTS TIMELINE AND FETCH CORRESPONDING DATA IN POINT AUDIT LOG Navigate to events history page Get timeline view of customer's events history with pagination parameters Return event history details, including related campaigns, offers, tags, points (earned and spent) Fetch point audit log with request parameters Return point history details, including points earned from transactions, points expired Evaluate points details for correspondence to events details (See Data Correspondence discussion below) Return full or partial point audit log Evaluate combined timeline and point audit data for display to customer Display combined data

API Endpoints & Constraints

Timeline

GET /v1/apps/:api_key/external/users/:external_id/timelines/NEW_VIEW
GET /v1/apps/:api_key/users/:user_id/timelines/NEW_VIEW

In general, the routes servicing timelines are rather flexible, as they can accept a customer's external or internal user ID. However, the following constraints apply:

  • Maximum number of rows returned is 1,000. So, the count parameter must be 1,000 or less. Note that page size is an influencing factor on performance, both latency and throughput (TPS).

  • It is recommended that timeline data be paginated or controlled with query parameters. You can use the Timeline API to control what views display for a customer’s front end experience. To learn more about controlling 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 the Retrieve Events for a Single View endpoint discussion.

  • The since parameter value, which is a timestamp, can be used to query for subsequent events. If no value is passed, all events are returned.

Point Audit Log

POST /api/1.0/point_audit_logs/fetch_point_audit_logs

  • Maximum number of rows returned is 1,000. So, the count parameter must be 1,000 or less. Note that page size is an influencing factor on performance, both latency and throughput (TPS).

  • The FromDate and ToDate parameters must express a date range of 1 year or less and MUST be provided

  • Maximum number of point account IDs and/or point source IDs is 10 if provided

  • Maximum number of ModificationTypes is 5 if provided.

  • Skip parameter value must be limited/provided as a 32-bit signed integer.

Data Correspondence

This use case describes a way to retrieve a event and loyalty data from two different sources - the customer's timeline and their point audit log. The event data that populates a timeline view is fairly basic; it is a history of a customer's account, including purchases, offer activity, and campaign activity. This timeline data is contained within the event stream payload, and it includes:

  • Type of event, such as purchase event.

  • Items relevant to event, such as items purchased.

  • Payments associated with event.

While the timeline does provide metadata about the events associated with a customer, much about the event's effects on the customer is absent. When such enhanced detail is required, the point audit log is an excellent source for supplementing the timeline data. It contains more detailed information about the event as it impacts the customer directly.

For example, consider a purchase. The timeline can show us IDs that track the event, timestamps, and payment data for the purchase. But the point audit log can show how many points a customer spent or how many expired. With it, you can present data that would be critical to the customer when they log in to a loyalty program and want to discover how many points they have in their point account.

When a development team builds out a page for displaying loyalty information to a customer, they can access data in the timeline along with the corresponding, more complex, data about the purchase event that resides in the point audit log. In this use case, the three kinds of data shown include:

  • Event metadata from the timeline, when the parameter set is PURCHASE_TRANSACTION

  • Base earn points data from the audit log , when the parameter set is INCENT.Outcomes

  • Bonus earn points data from the audit log, when the parameter set is for Behavior

If we wanted to retrieve all of the points earned from a purchase transaction detailed on the customer's timeline, we could present the following kinds of data:

Data Presented Endpoint Specified Parameter Specified JSON Response Excerpts
Timeline Event Data for Purchase GET /v1/apps/:api_key/external/users/:external_id/timelines/NEW_VIEW

GET /v1/apps/:api_key/users/:user_id/timelines/NEW_VIEW 		"event_type": PURCHASE_TRANSACTION"

Event Stream Identifiers

"event_stream_stream_id": "916a26bc-809d-11ed-9537-0242ac110008",
"event_stream_event_category_id": 3,
"event_stream_event_type_id": 12,
"target_id": 229,"timestamp": 1671564975000,
"created_at": 1671564979,

Payment Details

"payment_id": "transactioncampiagnwinbacktest",
"payment_time": "2022-12-20T04:30:00",
"receipt_code": "transactioncampiagnwinbacktest",
"retailer_id": "abed4f2d-5918-4e2a-995a-798c840d9e3d",

Point Audit Log Data for Regular Points Associated with Purchase POST /api/1.0/point_audit_logs/fetch_point_audit_logs "modification_type": "INCENT.Outcomes"

User Account Base Points

"account_name": "ACME's User Point Balance",
"point_account_id": "1db8bb75-df7e-499e-a05f-8cfc46703001",
"user_point_account_id": "4d25fb5e-ac12-490e-b802-b33410be9e54",
"modification": 1860.00,
"amount_spent": 0.00,
"amount_expired": 0.00,
"audit_type": 1,
"modification_type": "INCENT.Outcomes",
"modification_entity_id": "7d39cd3e-5760-4060-a995-24cd1a6e0137",
"spend_weight": 0,
"point_source_id": "0798ec5d-df7f-48b0-8a18-9884ca5a287b",
"point_source_name": "Base Earn",
"time_of_occurrence": "2022-12-20T19:36:15.787",

Point Audit Log Data for Bonus Points Associated with Purchase POST /api/1.0/point_audit_logs/fetch_point_audit_logs "modification_type": "Behavior"

User Account Bonus Points

"account_name": "ACME's User Point Balance",
"point_account_id": "1db8bb75-df7e-499e-a05f-8cfc46703001",
"user_point_account_id": "4d25fb5e-ac12-490e-b802-b33410be9e54",
"modification": 100.00,
"amount_spent": 0.00,
"amount_expired": 0.00,
"audit_type": 1,
"modification_type": "Behavior",
"modification_entity_id": "c5d588e7-801f-48ba-93d7-17e8ddfe5d92",
"spend_weight": 0,
"point_source_id": "23c01546-67f2-46f2-84ae-facc5bd5f9dc",
"point_source_name": "Bonus Earn",
"time_of_occurrence": "2023-01-19T18:40:13.93",

Take Note

Bear in mind that unifying, or combining this data, depends on the ability to link them. To that end, there are two fields that link the two sources and provide two views of the events pertaining to the customer:

  • ID for identifying the relevant timeline

  • transaction_id for identifying the relevant point audit log