Handling Customers#
End users/loyalty scheme members within Antavo’s ecosystem, are known as Customers. They are a fundamental unit within Antavo’s loyalty system and used throughout the database, platform, program, etc. This article shows how Antavo stores, accesses and processes Customers
Customer identifiers#
Antavo combines all of the customer activities, whether online, offline or mobile application and combines them into an omnichannel-friendly single profile. The ID attached to each individual profile identifies customers across all brand systems: the loyalty platform, the API, customer data imports and exports.
Internal ID#
Any unique combination of latin-based alphanumerical characters can be used to generate a customer ID. Antavo recommends not using email addresses, although it is a valid solution, for customer ID as there may be future difficulties in identification when/if customers change their email addresses.
The ecommerce ID is straightforward for implementing an online-only solution as all our ecommerce platform integrations (Magento, Shopify, Salesforce Commerce Cloud) support this by default. However, expanding a loyalty program to an omnichannel solution with in-store capabilities runs the risk of exposing the ecommerce ID. In this scenario, the best practice is the introduction of a new loyalty program ID that can be used across all backend systems e.g., using UUID.
Real world examples of how the customer id is used can be seen in the Transactions documentation.
External ID#
Enterprise-level loyalty system usually integrate with complex third-party systems. In order to reduce potential confusion and ID conflicts, it is possible to create and access customers using external IDs – a unique third-party customerID.
When configured, events can now be submitted using the external_id to select the configured customer external ID field and the customer field contains the value of this field, not the Antavo customer ID.
{
"action": "point_add",
"customer": "1234-5678-9123",
"external_id": "loyalty_barcode",
"data": {
...
}
}
Configuration steps and further examples can be found in the appendices.
Customer fields#
A new customer results in the creation of a Customer object. Individual customer data is stored in the customer object as attributes. The customer objects and corresponding API provide a user friendly and simple layer of abstraction to the event API stream, the primary data stream within Antavo. Customer data can be accessed via the Loyalty platform, the membership site (for members themselves), API/SDK access and the subsequent data integrated into existing devices and an Antavo accelerator-based mobile application.
There are three fields:
Built-in fields – These are standard fields consisting of mandatory fields, required for creating a valid customer, and basic field standard data. e.g., birth date, gender, location.
Custom fields – The customer profile can also be substantially enhanced with an unlimited number of custom fields e.g., favorite color, allergies, clothing size, preferred store. This allows better personalized customer communications and engagement with the customers.
Loyalty fields – Loyalty data is processed, according to the implemented loyalty mechanism, then assigned to these fields. Pre-defined metrics then define the status of a customer within the current tier e.g., number of collected points, membership tier, ….
The Customer object also has access to the Events log which contains a link to the customer’s events history. The Customer’s interactions with the loyalty scheme can be monitored directly via the Antavo SDKs e.g., daily logins, social shares or referrals or indirectly via the Events API e.g., purchases, returns, service subscriptions. This provides a complete non-exportable list of the customers’ activities within the loyalty program.
Loyalty IDs#
Customers’ loyalty IDs can be linked to the corresponding ecommerce accounts by creating a new field for the loyalty ID.
This can be used when sending GET/POST requests through the API.
The loyalty ID can be used at the POS in offline stores to query the customer data when scanning the customer’s membership pass.
Data channels#
Customer-initiated touchpoints in market strategy require customer information so the Antavo loyalty program implements various data channels to ensure that loyalty information can be used exactly wherever it is needed. e.g, email marketing provider, your ecommerce engine or the loyalty program.
Uninterrupted customer data synchronization is available using Antavo custom-built integration for many of the market leading CRM and marketing automation providers. Antavo can also daily push all data to a data warehouse within your data master platform. Please contact your technical project manager to help set up the data flow.
Customer data can also be created, accessed and modified on demand using Antavo’s Customer API and the customer ID. The Antavo customer API documentation contains specific details regarding GET/ POST access.
The Events API can also be used to send customer specific events e.g., opt-in, profile and opt-out events. Instructions can be found here about working with the Events API and these can also be mass imported using Antavo’s Events import module as documented here. Finally, a specific customer’s profile can be accessed in the Customer Insights menu in the Antavo backoffice.
Data compliance#
Data protection regulations like GDPR or CCPA, have made data protection a legal obligation as people have become increasingly concerned how their personal data is handled by companies.
Antavo is committed to process customers’ personal data with the highest security standards which are specified within our Data Protection Agreement. We can help you ensure that your loyalty data flow and processing is compliant with the applicable data protection terms.
Customer object#
Loyalty data purchasing statistics and personal information is stored on the individual customers in Antavo.
It can be accessed using the /customers/customer_id endpoint of the Customer API.
An example customer response, available here /docs/intro/example_customer_response.json can be broken down into standalone sections
Root#
This section contains the core loyalty information: Built-in customer and loyalty fields.
"id": "0519001",
"optin_at": 1631673016,
"last_login_at": null,
"updated_at": 1631689513,
"first_name": "An",
"last_name": "Example",
"email": "test@antavo.com",
"birth_date": "1980-01-16",
"gender": null,
"language": null,
"nickname": null,
"status": "active",
"score": 96000,
"spent": 32000,
"reserved": 0,
"spendable": 64000,
"pending": 0,
Profile#
Custom customer attributes are stored in the properties array. These attributes can be updated using the profile and/or rules depending on the individual configuration of the attribute. These attributes are configured in the Backoffice.
"properties": {
"auto_subscribed": true
},
Purchase#
A summary of purchase statistics is recorded in the customer object. Additional information, when needed can be accessed from corresponding checkout events from the event stream/history of the customer. The standard data includes:
purchase_total– every checkout transaction ever performed by the customerpurchase_count– The number of transactions performed by the customerpurchase_last_date– The date of the last transaction.
There is an additional statistical query which enables the calculation of purchases over custom time periods.
This query can be accessed via the API using the fields=purchases.ytd query.
The current options are:
todayyesterdaylast_monththis_month– aliasmtdthis_year– aliasytdthis_week– aliaswtdthis_quarter– aliasqtdlast_30dayslast_12monthslast_24months
{
"purchase_total": 4000,
"purchase_count": 7,
"purchase_last_date": "2021-08-19",
...
"purchases": {
"overall": {
"total": 4000,
"count": 7,
"items": 14
},
"mtd": {
"total": 1700,
"count": 3,
"items": 6
}
}
}
Note
count is the number of transactions in given period
items is the total number of purchased items in given period
// accessing all purchase history as an array
volt: {{ customer.extensions.purchases.history }}
// specific time options can be accessed as an array
volt: {{ customer.extensions.purchases.last_24months }}
// individual array elements can also be selected
volt: {{customer.extensions.purchases.mtd["total"] }}
volt: {{customer.extensions.purchases.last_month["count"] }}
Expiring points#
The expiration of a customer’s points can also be returned in a Customer API request by using the fields=expiring_points query.
This returns an array listing timeframes for points expiration.
"expiring_points": {
"today": 0,
"this_month": 0,
"this_year": 123,
"next_month": 123,
"next_year": 0,
"reset_date": "2022-12-25"
},
An array of points expiration with corresponding dates of a customer’s points can also be returned in a Customer API request by using the fields=expiring_points.history query.
...
"history": [
{
"date": "2022-12-31",
"points": 1234
}
]
....
Accounts#
An individual detailed breakdown of the customer point information is also accessible from the customer object for brands using multi-account .
For each enabled account
id – The system name for the account
name – The human friendly label used for the account throughout the Backoffice
earned – The total numbers of points earned in this account.
spent – The total number of points spent in this account.
pending – The total number of pending points in this account.
reserved – The total number of reserved points in this account.
expired – The total number of expired points in this account.
spendable – The total number of spendable points in this account.
burn_rates – These are currency-dependent burn rates set in the Backoffice.
amount – The value of the points
points – The number of points to be burnt
currency – The selected currency
converted_amount – The currency value of all spendable points eligible for point burn
unconverted_points – The number of points not used in the maximum point burn conversion
"accounts": [
{
"id": "doc1",
"name": "Test1",
"earned": 12705,
"spent": 1056,
"pending": 0,
"reserved": 0,
"expired": 0,
"spendable": 11649,
"burn_rates": [
{
"amount": 100,
"points": 200,
"currency": "GBP"
"converted_amount": 58,
"unconverted_points": 49
},
{
"amount": 100,
"points": 50,
"currency": "HUF"
"converted_amount": 232,
"unconverted_points": 49
}
]
}
]
Tiers#
Tier structures for customer are proceeded and configured using the Tiers module in the Antavo Backoffice. For each tier available in the platform
id – The system name for the tier level.
name – The human friendly label used throughout the Backoffice.
threshold - The number of tier status points required for entering this tier.
points - The current number of tier status points. These are not loyalty points but are separate entities awarded based upon the rules set in tier configuration.
points_after_expiration - The number points left following a tier expiration.
structure - An array containing the id and name of the tier structure
next - An array stating the id, name and points required for promotion into the next tier. This is not returned for the top tier in a tiers structure.
"tiers": [
{
"id": "T0",
"name": "Basic",
"since": "2021-09-15T11:11:15+08:00",
"threshold": 0,
"points": 0,
"points_after_expiration": 0,
"structure": {
"id": "basic",
"name": "ExampleTier"
}
"next": {
"id": "T1",
"name": "Standard",
"points": 12345
}
},
],
Tier structure can also be accessed via the Entities API.
Tiered Campaigns#
The Tiered campaigns module is designed to encourage customers to make repeated interactions with the loyalty program by providing milestone-based incentives. The customer response will be extended with a campaigns array.
"campaigns": [
{
"id": "63772885e9af5b34933d4aa6",
"occurrences": [
{
"id": "occurrence_1",
"pending_points": 0,
"awarded_points": 1560,
"status": "completed",
"start_date": "2022-11-01T07:36:00+01:00",
"end_date": "2022-12-01T07:36:00+01:00",
"evaluation_date": "2022-12-01T07:36:00+01:00"
}
]
}
]
Customer journey#
A customer’s journey in the Antavo loyalty program can be described by three major statuses and these determine how the customer data is handled. Basic marketing data consent is the minimum requirement for each step:
Inactive#
The pre-enrollment activities of a customer. An Inactive customer is created in Antavo’s database by sending subscribe event events via the Events API. An inactive customer’s profile can not be located via the Antavo Enterprise Loyalty Cloud but accessible using other available channels. This is most commonly used in data migration to the Antavo Enterprise Loyalty Cloud, as it reserves pre-existing customers id and reduces the risk of data conflicts, and as a way of “freezing” accounts without any data loss. Local data processing regulations and policies should be consulted to ensure the legal basis for processing this type of personal data.
Active#
Active customers are consenting members of your loyalty program. Active membership means that customers can enjoy benefits, collect points with their actions and claim rewards. Customers express their intent to join the loyalty program by accepting the terms and conditions and giving their consent to process their personal data. An opt-in event must be sent at the end of any type of enrollment process in order so that the Antavo Enterprise Loyalty Cloud (ELC) can activate the customer. See here for the ways that customers can be enrolled
Whilst a customer is an active member. you can:
use the profile event to update customer attributes
track each member’s activities by searching their profile on the Antavo Enterprise Loyalty Cloud
Opted-out#
A customer deliberately leaves the loyalty program. Opting out results in the complete anonymization in Antavo’s database with the opted-out status. This means that their membership history with all the benefits they earned is deleted for good. When planning the opt-out process, we suggest the creation of an option for customers to delete their accounts separately from their webstore registration but you need to make sure that their loyalty membership is deleted when they choose to leave your webstore as well. To un-enroll a customer, you need to send an opt-out API event. As soon as the opt-out event is sent, the customer is removed from the loyalty program, not searchable on the Antavo Enterprise Loyalty Cloud and Antavo no longer stores identifiable personal data about the customer. A customer can be forcibly opted-out if they have violated the terms and conditions of the loyalty scheme.
Customer lifecycle#
The Antavo Enterprise Loyalty Cloud can only fully work with customers who have enrolled (opt-in) and remain active.
Antavo has been carefully designed to mirror industrial standard registration procedures so that loyalty scheme enrollment so customers can seamlessly join a loyalty program when they create an account. Enrollment can also be initiated at a later time by the customer, in a separate step. The following graphic shows a typical ecommerce registration procedure example with the key enrollment steps and corresponding Antavo customer statues and triggering events.
It’s also possible to mass-enroll your previous customer base providing that they have provided their explicit consent to be a member of the loyalty program. Such mass-enrollments should normally happen through throttled API requests or file drops to Antavo.
Please read the detailed ecommerce and in-store guides to learn more about implementing different customer journeys in Antavo.
Loyalty data also can be securely accessed using the API interface enabling server-based process and displaying of loyalty information within a framework of your choosing. The Customer API focuses on the direct access of customer information and the Display API uses customer data for the generation of customer-facing portals.