About the SessionM transaction schema
At a glance
SessionM transaction schema
This article describes how transactions are represented in SessionM loyalty programs. The article describes the base transaction schema, and how you can use custom objects to extend the schema to include segemnt-specific attributes in loyalty transactions. The article concludes with a scenario that illustrates how you can use custom objects in the SessionM platform.
Client applications use the transaction payload to send purchase-related data to the SessionM platform. The base transaction payload has a set of pre-defined collections and properties that describe the types of data that client applications can send to SessionM. For example, the default transaction payload includes the items collection that has the quantity and unit_price properties.
Custom objects allow you to add user-defined properties that contain data specific to your loyalty program that are not included in the standard transaction schema. For example, an airline could add custom properties that identify a flight's point of departure, destination and number of miles flown. You can group related properties into a collection. For example, you could group the properties describing a flight into a collection named "Flight Info".
You can use custom objects as qualifiers when building loyalty rules. See Scenario: Using custom objects to build loyalty rules for an example.
Base transaction schema: Sending purchase data to SessionM
Client applications send purchase-related data to the SessionM platform through the transaction schema; this is the only way to send transaction (purchase-related) data to SessionM.
The following image shows the base transaction schema.
The base transaction schema has four collections:
-
header: Identifies the transaction, including the transaction ID, retailer and store. The transaction schema has a single header collection.
-
items: Identifies the items purchased, including the quantity, price and the retailer. The transaction schema can have multiple items collections.
-
payments: Identifies the payment, including the type and amount. The transaction schema can have multiple payments collections.
-
discounts: Identifies the discount (if any) applied to the transaction, including the amount and source. The transaction schema can have multiple discount collections.
The following image shows the base transaction schema populated with the standard properties under each header:
See the SessionM Transaction API documentation for more information. The process endpoint describes the objects and properties in the base transaction schema.
Custom objects: Adding segment-specific data to transaction schema
The properties of a transaction differ by segment. For example, airlines require properties for flights, airports and so on. Hospitality requires properties for bookings, reservations and so on. SessionM provides an extensible transaction schema that adapts to your loyalty program's unique data requirements.
Custom objects allow you to add user-defined properties that contain data specific to your loyalty program that are not included in the standard transaction payload. For example, an airline could add custom properties that identify a flight's point of departure, destination and number of miles flown. You can group related custom properties into a collection. For example, you could group the properties describing a flight into a collection named "Flight Info".
The following image shows a transaction schema that has been extended with a collection named "Flight Info". The "Flight Info" collection contains a set of custom properties that describe specific details of the flight.
Examples of data schemas that have been extended to support industry-specific requirements follow. The highlighted Items are custom objects (either properties or collections) added to the base transaction schema.
Retail custom schema example
See Provide multiple outcomes from a single rule for a use case based on this schema.
QSR custom schema example
See Reward members for using an external delivery service for a use case based on this schema.
Travel & hospitality custom schema example
See Invite members who pile on the miles to an exclusive "hidden" tier for a use case based on this schema.
Properties
A property is a segment-specific data element that you want to supply to the SessionM platform for processing in segmentation, rules and reporting.
The example collection above has properties for the origin, destination and miles flown. You could use the "origin" property to build a rule where members on a flight departing from Santiago, Chile earn 100 bonus points. Or you could build a rule where members who have a total "miles flown" greater than 10,000 receive a 20% discount on their next flight.
A property has the following attributes:
| Attribute | Description |
|---|---|
| Status | Indicates whether the property is active or inactive. SessionM does not recognize or process an inactive property. Designate a custom property as inactive while you are finalizing the schema design and then activate it when the payload is ready. |
| Property Type |
A property can have the following types:
|
| Property Name | Identifier for this property used in SessionM platform interface. |
| Property Symbol (API) | Identifier for this property used in SessionM APIs. Only alphanumeric characters allowed with no spaces. Once this value is saved, it cannot be changed. |
| Required Field | When enabled, any transaction that does not include this field in the payload fails validation when the transaction is ingested into SessionM and so is rejected. No loyalty rules are evaluated or outcomes are awarded until the transaction is updated to include the required field and then re-submitted. |
Custom list
A custom list (or taxonomy) enumerates the valid values for a property. Custom lists make defining rules easier, since it presents you with the list of acceptable values for the property being used in the rule. The list must be in JSON format, as shown below:
{
"iata_type": {
"airport",
"bus",
"harbor",
"heliport",
"seaplane",
"military",
"railway"
}
}Collection
A collection is a container object that holds a set of properties. A collection has the following attributes:
| Attribute | Description |
|---|---|
| Status | Indicates whether the collection is active or inactive. SessionM does not recognize or process an inactive collection. Designate a collection as inactive while you are finalizing the schema design and then activate it when the payload is ready. |
| Collection Name | Identifier for this collection used in SessionM platform interface. |
| Collection Symbol (API) | Identifier for this collection used in SessionM APIs. Only alphanumeric characters allowed with no spaces. Once this value is saved, it cannot be changed. |
Scenario: Using custom objects to build loyalty rules
This scenario demonstrates how you can use properties in conditions and outcomes in a current purchase rule. Assume that Arctic Airways has defined a custom collection named "Flight Info", shown below:
Arctic Airways has recently opened a new hub in Helsinki, Finland and wants to reward members who fly long-distance out of that hub. It adds a purchase benefit to its program where members whose 1) flight departs from Helsinki with a distance greater than 1000 miles 2) receive three points for every mile flown.
The following image show the condition and outcome.
The condition uses two custom properties, start_location, miles_flown, joined by the AND operator (indicating that both must be true for the condition to evaluate as true). The outcome uses the miles_flown custom property to determine the size of the point award.
Member experience
-
Astrud is currently a member of Arctic Airways’ Bronze tier, with 9000 miles flown this year and 10,000 spendable points.
-
On June 6th, Astrud purchases a flight for October 12th. The flight originates in Helsinki, has a distance of 1200 miles, and costs $360.
-
The reservation transaction, with extended data captured in the custom object, is sent to the SessionM platform. No outcomes are awarded because Arctic Airways only awards points after the flight has been completed.
-
On October 12th, with the flight completed, the miles and points are processed and awarded to the customer.
-
Astrud moves to the Silver tier of the Loyalty program, with 10,200 miles flown and a spendable point balance of 12,600 points.
See How do rules work within tiers? for more examples of using custom objects in the SessionM platform.