Customers
The target audience of a loyalty program is known as customers in Antavo’s ecosystem. This document provides all the necessary information to effectively manage customer profiles, attributes, and lifecycle stages.
Customer profile
When an opt_in event with an unknown customer ID is submitted, a new customer object is created in the database to store all their information, like name, email, and purchase history, saved as attributes.
If anonymous event registration is enabled, any other event may also create customer objects.
The customer attributes stored and the historical events associated with the customer (including customer activities whether online, offline, or mobile) together form the complete customer profile.
Customer attributes
Attribute types
There are three types of customer attributes stored in the customer profile :
- Built-in attributes: Default attributes provided by Antavo. (e.g., ID, status, birth date, gender).
- Custom attributes: The customer profile can also be substantially enhanced with an unlimited number of custom fields (e.g., favorite color, allergies, clothing size, preferred store) through the Settings menu of the Management UI. This allows better personalized loyalty incentives and engagement with the customers.
- Read-only attributes: Special type of built-in attributes. Their values are calculated by the Loyalty Engine’s internal services based on the implemented loyalty program mechanisms (e.g., number of collected points, customer’s membership tier). These attributes cannot be overwritten directly by API, imports, or by other means.
Customer identifiers
Every individual customer profile in the loyalty program is tagged with a unique customer ID, stored in the _id
customer attribute. This ID is the key identifier across all workspace systems, including the Management UI, customer database, API endpoints, and customer data imports and exports. For external systems like POS in offline stores, configuring them to identify customers as loyalty members based on this ID is essential for seamless integration.
Creating a customer ID
The customer ID can be any unique combination of Latin-based alphanumerical characters and dashes. While email addresses can technically be used, it’s strongly discouraged. Since the customer ID is case-sensitive, variations in email casing can lead to duplicate profiles. Furthermore, email addresses are prone to change, which can break the continuity of customer profiles if updated.
As mentioned, the customer ID is case-sensitive, meaning that slight variations in casing (e.g., [email protected]
and [email protected]
) will create distinct profiles. Therefore, ensuring consistency in ID casing across all integrations is critical to avoid duplicate customer profiles.
E-commerce and Customer IDs
E-commerce platforms that you integrated with Antavo, such as Magento, Shopify, Salesforce Commerce Cloud, provide their own e-commerce IDs, which can also serve as Customer ID in the loyalty program. However, there's a caveat. If you plan to expand the loyalty program into an omnichannel solution with in-store capabilities, using e-commerce IDs can expose these IDs, compromising security.
The best practice: UUIDs
To maintain robust security and avoid potential pitfalls, Antavo recommends using a non-changeableUUID for loyalty program membership. These UUIDs are specifically designed to be immutable and cannot be reverse-engineered to reveal e-commerce or POS IDs, providing a higher level of security and integrity.
External IDs
Using external IDs offers an effective solution for transmitting data from external systems that use different customer IDs different from the loyalty membership ID. It enables Antavo to recognize customers based on various IDs from other systems. Learn more about this option below.
Customer lifecycle
Stages
Understanding the various stages and statuses within the loyalty program is crucial for effective management and seamless integration. Here’s the breakdown of these stages:
Potential members
Potential members are individuals who might join the loyalty program in the future.
Non-loyalty member guest customersData from guest checkouts can be registered without linking it to a specific profile. Once these customers enroll in the loyalty program and their customer profile is created in Antavo, they can claim their previously registered guest transactions. For more details on this process, refer to the Transaction lifecycle document.
Here are the statuses that define potential members of the program who have customer profiles registered in Antavo:
- Inactive: This status indicates customers who aren’t yet registered in the loyalty program. Often used to track pre-enrollment activities, it ensures a smooth migration of historical data from other systems before customers officially enroll in the program. An inactive customer is created in Antavo’s database by sending any event via the Events API with a customer ID that hasn't been attributed to any other customer yet.
These profiles are not listed in the Management UI by default; they are only accessible through searching. - Pending: This status applies to customers who have started the registration process but haven’t confirmed their registration via email verification. This step is optional and can be added through the Customer login module. The pending status indicates incomplete registration.
NoteLocal data processing regulations and policies should be consulted to ensure the legal basis for processing personal data before official enrollment into the program.
Registered members
Registered members are customers who are actively enrolled in the loyalty program. See the various enrollment methods below.
- Active: This status indicates fully registered members who enjoy all benefits of the loyalty program. Active customers can participate in loyalty program activities and earn incentives. Their profiles can be managed through the Customer insights menu of the Management UI.
- Suspended: Members whose memberships are restricted due to fraudulent behavior fall under this status. Suspension can be applied manually through the customer profile, by workflows, or via the submission of the
suspend
API event.
Suspended members can earn points but are restricted from spending them or claiming rewards. This status can be lifted to revert the customer to active status.
Former members
Former members are customers who previously had an active status in the loyalty program.
- Opted-out: This status indicates customers who have voluntarily left the loyalty program or have been removed due to violations. Opted-out status results in complete anonymization of their data in the database.
Learn more about the unenrollment below. - Banned: Customers who have been banned due to fraudulent activities fall under this status. Banning is done manually through the Customer insights menu of the Management UI. Banned customers cannot earn or spend points or redeem rewards. This status can be reversed by a Management UI user.
Customer lifecycle management
Enrollment
Antavo seamlessly integrates with standard registration procedures, allowing customers to join the loyalty program as part of their account creation process in external systems. Customers can also enroll at a later stage. Enrollment occurs through the registration of the Opt-in (opt_in) event.
Methods of registering the Opt-in event:
Standard event registration
As detailed in the Actions and Events article, standard event sources are applicable here. Below is an example of a request using the Events API:
POST /events
Host: api.<environment>.antavo.com
Authorization: ANTAVO-HMAC-SHA256 Credential=TEST_API_KEY/20181207/test/api/antavo_request,
SignedHeaders=date;host,
Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc
"customer": "09d9e415-521b-48ef-9b44-fbdc8dc0189c",
"action": "opt_in",
"data": {
"email": "[email protected]",
"first_name": "Alyson",
"last_name": "Nash",
"handler": "alyson-nash",
"referrer": "e4ff6e29-9af0-428c-a4e6-2908f9e07305"
}
}
Display API
The opt-in event can also be registered via the customers/customer_id/opt-in
Display API endpoint. Here’s an example request using the Display API:
{
"password": "string",
"confirm_password": "string",
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"birth_date": "1970-01-01",
"gender": "female",
"language": "en",
"phone": "36307741144",
"mobile_phone": "36307741144",
"handler": "john.doe"
}
The response from the endpoint includes the customer object along with customer attribute data.
Customer imports
For bulk customer enrollments, the Imports module of the Management UI is an effective solution. Instead of overwhelming the APIs, compile events into a CSV file and import them in bulk. This approach is particularly advantageous for migrating customers by third-party systems where direct API integration is impractical.
Comprehensive instructions for using the Imports module and uploading files are available in the Imports module user manual. Uploaded files are processed asynchronously and the progress can be tracked via the Management UI.
Additional processes
Mass enrollment
For mass-enrolling your existing customer base, consider using the /events/bulk
, or importing Opt-in events through Antavo's Imports module.
Verification process
If a verification process (provided by the Customer login module) is configured, use the customers/-/verify
endpoint, sending the generated token to complete the enrollment. Until verification is completed, the customer’s status remains pending.
NoteOnce the opt-in event is properly registered through any of the methods mentioned, the customer’s status is updated to active.
Unenrollment
Customers can be removed from the loyalty program through the registration of the Opt-out (opt_out
) event.
Methods of registering the Opt-out event
Standard event registration
As detailed in the Actions and Events article, standard event sources can be used here. Below is an example request using the Events API:
POST /events
Host: api.<environment>.antavo.com
Authorization: ANTAVO-HMAC-SHA256 Credential=TEST_API_KEY/20181207/test/api/antavo_request,
SignedHeaders=date;host,
Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc
{
"customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
"action": "opt_out",
"data": {
"reason": "The customer decided to leave the loyalty program voluntarily."
}
}
Manual action
Management UI users can manually remove customers by clicking the Opt out button on the customer profile. The automatically generated opt_out
event will include the admin
attribute, which stores the ID of the user who registered for the event. Find instructions in the Customer insights user manual.
As soon as the opt-out event is sent, the customer’s status is updated to opted-out and the customer is removed from the loyalty program.
Data handling after opt out
Opt-out results in the anonymization of the customer in Antavo’s database by hashing the customer ID and all information Antavo stores about the customer. This ensures the customer data is unidentifiable based on Antavo’s retention policy. Consequently, the customer will no longer be searchable in the customer database.
When planning the opt-out process, it’s advisable to create an option for customers to delete their accounts separately from their e-commerce store registration. Ensure that their loyalty membership is deleted when they choose to leave your e-commerce store, and Antavo no longer stores identifiable personal data about the customer.
Re-enrollment
Customers who had previously enrolled and then unenrolled can rejoin the program at any time through the standard enrollment process. Antavo anonymizes all customer data upon unenrollment, making the customer unidentifiable and any previously stored data non-recoverable. Consequently, when a customer re-enrolls, they are registered in a loyalty program with a completely new customer profile. The customer can have the same customer ID they had before if no customer has been assigned to it since then.
Customer attribute data sources
Configured loyalty mechanisms may automatically generate and update customer data attributes, such as information related to tier membership and point balances.
Non-read-only attributes, however, can be submitted or updated directly by submitting Profile (profile
) events with the following methods:
Standard event registration
As detailed in the Actions and Events article, standard event sources can be used here. Here’s an example request using the Events API:
POST /events
Host: api.<environment>.antavo.com
Authorization: ANTAVO-HMAC-SHA256 Credential=TEST_API_KEY/20181207/test/api/antavo_request,
SignedHeaders=date;host,
Signature=77a273065129d9967e6569c750bd1401e6bccae5f3876cd48708d593726e20bc
{
"customer": "9f60a422-1e56-46c1-ae7a-b3fae778fac8",
"action": "profile",
"data": {
"email": "[email protected]",
"first_name": "Johnie",
"last_name": "Caris",
"favorite_color": "black",
}
}
Management UI
Individual customer profile data can be registered and updated through the Personal information tab of the customer profile page in the Management UI. Refer to the Customer insights user manual for more information.
NoteLearn more about how events and their associated data can be registered and accessed in the Actions and Events article.
Accessing customer attribute data
Customer attribute data can be accessed in various ways to ensure that loyalty information is available for display on the membership site or for customer data analysis.
Customer API
The Customer API provides programmatical access to data stored in customer attributes, allowing the development of applications or integrations that require direct access to customer information.
Here’s an example response from the Customer API:
{
"first_name": "John",
"last_name": "Smith",
"nickname": "Johnny",
"email": "[email protected]",
"birth_date": "1969-12-25",
"gender": "Male",
"language": "en",
"currency": "GBP",
"status": "Active",
"score": 100,
"spent": 20,
"reserved": 0,
"spendable": 50,
"pending": 20,
"image_url": "<http://example.com/image.png">,
"optin_at": 1577836800,
"last_login_at": 1593561600,
"updated_at": 1593561623,
"purchase_total": 100,
"purchase_count": 2,
"purchase_last_date": "2020-10-01",
"mobile_phone": "123-456-789",
"accounts": [
{
"id": "main_account",
"name": "Main account",
"earned": 12705,
"spent": 1056,
"pending": 0,
"reserved": 0,
"expired": 0,
"spendable": 11649,
"burn_rates": [
{
"amount": 100,
"points": 200,
"currency": "GBP"
}
]
}
],
"tiers": [
{
"id": "T0",
"name": "T0",
"since": "2022-05-02T12:57:41+02:00",
"threshold": 0,
"expdate": "2023-01-11T00:00:00+01:00",
"points": 100,
"points_after_expiration": 10,
"structure": [
{
"id": "basic_tiers",
"name": "Basic tiers"
}
]
}
],
"referrer": null,
"referrals": 2
}
The response includes various customer attributes, both built-in and custom. Information regarding accounts, tiers, and tiered campaigns is provided if the respective (Tiers, Multi-accounts, and Tiered campaigns) modules are enabled in the workspace.
You can also request data through extensions; more information on this can be found below.
NoteOther customer-related data not stored in customer attributes (e.g., claimable rewards or challenges completions) can be retrieved using the Display API. This data can be displayed to customers on a dedicated membership site.
Management UI
Individual customer’s data can be checked by opening their profile under the Customer insight menu of the Management UI. Refer to the Customer insights user manual for more details.
Exports
The list of attributes and all data can be exported through the Exports module and processed externally if necessary. Initiate the export process by selecting the customer attributes of interest and other filters, then request the export. Downloading will start as soon as the data is ready.
Data extensions
To optimize performance, certain customer-related data is aggregated into separate objects called data extensions instead of being stored directly on the customer object. This approach reduces the load on the primary customer database, ensuring faster query responses and improved overall system efficiency. Data extensions can be queried using specific query string parameters when requesting data through the /customers/{customer_id
endpoint of the Customer API.
Purchases
Using the fields=purchases
parameter, you can access the calculated values of customers’ purchases (total monetary value of purchases, number of purchases, and number of purchased items) over a defined time period. Here are the available options:
today
yesterday
last_month
this_month
– aliasmtd
this_year
– aliasytd
this_week
– aliaswtd
this_quarter
– aliasqtd
last_30days
last_12months
last_24months
Here’s an example of the purchases section of the API response using the fields=purchases.mtd
parameter:
"purchases": {
"overall": {
"total": 4000,
"count": 7,
"items": 14
},
"mtd": {
"total": 1700,
"count": 3,
"items": 6
}
}
Historical purchase data with corresponding dates can also be accessed using the fields=purchases.history
parameter.
Example of the array of purchases:
"purchases": {
"overall": {
"count": 4,
"items": 2,
"total": 322
},
"history": {
"2022-07-08": {
"count": 1,
"items": 1,
"total": 10
},
"2023-01-25": {
"count": 1,
"items": 0,
"total": 112
},
"2023-02-01": {
"count": 1,
"items": 1,
"total": 100
},
"2023-01-31": {
"count": 1,
"items": 0,
"total": 100
}
}
}
The purchases data extension can also be accessed in the workflow editor using Volt templating:
// 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
Number of expiring points
The method for retrieving information about the number of a customer’s expiring points differs depending on whether the Multi-accounts module is enabled in your workspace.
If the Multi-account module is enabled, information about the expiration of a customer’s points for each account can be retrieved using the fields=accounts.expiring_points
query string parameter. This returns information about the number of points to expire in specific time periods.
Here’s an example of the expiring points section of the API response using the fields=accounts.expiring_points
parameter:
"accounts": [
{
"id": "points",
"name": "Points",
"earned": 2100,
"spent": 0,
"pending": 0,
"reserved": 0,
"expired": 0,
"spendable": 2100,
"burn_rates": [
{
"amount": 1,
"points": 100,
"currency": "USD",
"converted_amount": 21,
"unconverted_points": 0
}
],
"expiring_points": {
"today": 0,
"this_month": 0,
"this_year": 123,
"next_month": 123,
"next_year": 0,
"reset_date": "2022-12-25"
}
}
],
When Multi-accounts is not enabled, the fields=expiring_points
query parameter returns the overall point expiration data for the customer, without segmentation by individual accounts.
Here’s an example of the expiring points section of the API response using the fields=expiring_points
parameter:
"expiring_points": {
"today": 0,
"this_month": 0,
"this_year": 123,
"next_month": 123,
"next_year": 0,
"reset_date": "2022-12-25"
},
Point expiration history
Point expiration occurrences with corresponding dates can also be accessed using the fields=expiring_points.history
parameter.
ImportantPlease note that while the point expiration history can be used with the Multi-accounts module enabled, it is only available in a consolidated format, and there is no separate parameter for retrieving it by individual accounts.
Here’s an example of the array of point expiration occurrences using the fields=expiring_points.history
parameter:
"expiring_points": {
"next_month": 20,
"this_month": 0,
"history": [
{
"date": "2022-10-07",
"points": 50
},
{
"date": "2022-12-08",
"points": 0
},
{
"date": "2024-07-01",
"points": 20
},
{
"date": "2024-08-01",
"points": 100
}
],
"this_year": 120,
"next_year": 0,
"today": 0
},
External identifiers
NoteUsing external identifiers requires the Uniform customer profile module to be enabled, as the customer attribute needs to be available as part of the opt-in event. Please contact the Antavo Service Desk if you need assistance enabling this module.
Using external IDs enables seamless integration of various external systems with the loyalty program, allowing Antavo to associate incoming data with loyalty profiles, even when using different identifiers than the customer ID used by the loyalty program, such as the e-commerce ID.
Any string-type customer attribute can be designated as an external ID by adding the external_id
tag to the attribute under the Customers page of the Management UI. This is particularly useful if customer data is submitted by multiple integrated services and applications that do not share the same customer identifier.
Requirements of an external ID customer attribute are:
- The tag can only be added to string-type attributes.
- The name of the attribute should not match any Antavo module names.
NoteAdding the
external_id
tag is irreversible. Once added, it cannot be removed.
NoteIn general, customers cannot be created in Antavo using only the external ID. Currently, creating customers with an external ID is only possible if the Salesforce Sales Cloud integration is enabled in your workspace and its configuration is set to allow the synchronization of customer records from Salesforce to Antavo (i.e., the primary source configuration is set to Salesforce only or both).
Practices of using external IDs
Customer and Display API
Customer data and Display API functionalities can be accessed using external IDs at every endpoint of the Customer API and Display API.
Example: The customer data can be retrieved using a GET
request sent to the Customer API to <https://api.{environment}.antavo.com/customers/external_id_field:external_id_value>
Example: To retrieve the list of claimed rewards using an external ID, a GET
request should be sent to the Display API to
<https://api.{environment}.antavo.com/customers/external_id_field:external_id_value/rewards>
Events API and Entities API
Customers can be created through the endpoints of the Events API and Entities API using external IDs.
Example: Bulk submission of events using a POST
request to events/bulk
endpoint where the default customer ID and an external ID are used within one single request.
{
"events": [
{
"customer": "280e674c-c4ea-4a30-987a-d9267d1a5018",
"action": "opt_in",
"data": {
"loyalty_barcode": "1234-5678-9123"
}
},
{
"customer": "280e674c-de2a-4a30-987a-d9267d1a119",
"external_id": "loyalty_barcode",
"action": "profile",
"data": {
...
}
},
{
"customer": "ea2a593c-d089-44b6-96e6-0a812247cda2",
"action": "point_add",
"data": {
"points": 1
}
}
]
}
Example: Bulk submission of customers using a PUT
requests to /entities
where the default customer ID and an external ID are used within one single request.
{
"entities": [
{
"method": "PUT",
"type": "core/customer",
"id": "280e674c-c4ea-4a30-987a-d9267d1a5018",
"data": {
"barcode": "1234-5678-9123"
}
},
{
"method": "POST",
"type": "core/customer",
"id": "loyalty_barcode:1234-5678-9123",
"data": {
"first_name", "Test"
}
},
{
"method": "GET",
"type": "core/customer",
"id": "ea2a593c-d089-44b6-96e6-0a812247cda2"
}
}
Management UI
Accessing customers in the Management UI is also possible using an external ID through the following URL:
<https://loyalty.{environment}.antavo.com/{workspace_id}/customers/{external_field:external_customer_id}>
Updated 3 months ago