[go: up one dir, main page]

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 customers

Data 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.
📘

Note

Local 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.

📘

Note

Once 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.

📘

Note

Learn 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.

📘

Note

Other 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 – alias mtd
  • this_year – alias ytd
  • this_week – alias wtd
  • this_quarter – alias qtd
  • 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.

🚧

Important

Please 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

📘

Note

Using 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.
🚧

Note

Adding the external_id tag is irreversible. Once added, it cannot be removed.

📘

Note

In 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}>