How to connect an API-first loyalty engine with marketing automation? Open Loyalty + Bloomreach example

In practice: connecting Open Loyalty and Bloomreach

The use case

A simplified summary of what our partner required:

Setup

• Two point currencies: 

1. “Permanent” – Doesn’t expire;
2. “Temporary” – Expires after a set amount of time.

• Three tiers with point thresholds, plus custom tiers:

1. VIP members – get extra points and their temporary points don’t expire;
2. Employees with exclusive benefits – receive double points on all activities.

Member activities

• Purchasing a product awards Permanent points. The amount depends on the product category;
• If a member loses a tier due to expired points, they receive an opportunity to get more temporary points by using their purchased products in a certain way.

Communication

• Communication is personalized by combining customer data, transactional, and behavioral data;
• Important events trigger personalized motivational messages, for example: gaining points and advancing tiers;
• Event messages can also build urgency and direct members to certain behaviors. For example, when their points are about to expire or if they are about to face a downgrade.

Example of message combining setup, activities and communication:

Hey John,

You're about to lose a 20% discount coming from Gold Tiers as your points will expire in 7 days. To prevent from losing a discount and Gold status, here are some things you can do:

• Buy ski socks for 10% less than usual (same brand as the last one you bought)
• Complete the “Active Challenge” and make 2 reviews in the next 7 days

Requirements and assumptions

This example demonstrates the initial stages of designing an integration layer using AWS services, focusing on the connection between Open Loyalty and Bloomreach. 

The emphasis here is on simplicity, with performance, security, and reliability presented as overarching considerations for future iterations. 

API or webhook?

Our use case demands high responsiveness. Relying on traditional API request mechanisms would not be efficient, and webhooks emerge as a solution to address this need, embodying the "don't call us, we call you" pattern.

In contrast to traditional APIs, where data updates necessitate frequent polling, webhooks provide a more efficient alternative. The conventional approach of polling is effective when the timing of data retrieval is known in advance. However, it becomes cumbersome and expensive when searching for real-time updates. Frequent data requests, comparisons, and asynchronous processing can introduce operational complexities and financial overheads that may significantly impact business operations.

Webhooks, in an event-driven setup, enable almost real-time communication communication. The external system notifies your components when an important business event happens, eliminating constant polling. This proactive system enhances efficiency and responsiveness, informing your system about business events in real-time for seamless synchronization. This event-driven model streamlines communication and promotes a cost-effective integration of components in your business architecture.

Overview

Example integration architecture/data flow

Step-by-step implementation

For a quick start, the AWS console allows users to build the integration within a browser, bypassing the need for advanced Terraform or Terragrunt knowledge. While NodeJS is showcased for AWS Lambda, the service supports various languages. 

This basic example serves as a starting point, with room for refinement and consideration of performance and security complexities in subsequent integration phases.

export const handler = (event, context, callback) => {
    event.data = JSON.stringify({
      "customer_ids": {
        "registered": event.data.customer.email,
      },
      "properties": {
        "tier_id": event.data.level.levelId,
        "tier_name": event.data.level.name,
        "tenant_code": event.storeCode,
        "levelMove": (event.data.level.levelMoveUp == true) ? 'up' :'down',
      },
      "event_type": "loyalty_challenge"
    });
    event.options = {
        hostname: 'api-demoapp.exponea.com',
        path: '/track/v2/projects/{projectId}/customers/events',
        method: 'POST',
        headers: {
            'accept': 'application/json',
            'Content-Type': 'application/json',
            'Content-Length': event.data.length,
            'Authorization': 'Basic XXXX', // Put authorization header here
          },
    };
    
    const req = https.request(event.options, (res) => {
        let body = '';
        res.setEncoding('utf8');
        res.on('data', (chunk) => body += chunk);
        res.on('end', () => {
            // If we know it's JSON, parse it
            if (res.headers['content-type'] === 'application/json') {
                body = JSON.parse(body);
            }
            callback(null, body);
        });
    });
    req.on('error', callback);
    req.write(event.data);
    req.end();
};

Exchanging data between systems

Open Loyalty is an active system here. As an event-driven engine, Open Loyalty detects an important business event, “Tier upgrade”.

Payload

{
  "eventName": "string",
  "storeCode": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "data": {
    "customer": {
      "customerId": "string",
      "email": "string",
      "phone": "string",
      "loyaltyCardNumber": "string"
    },
    "level": {
      "levelId": "string",
      "name": "string",
      "levelMoveUp": true,
      "levelMoveDown": false
    }
  }
}

Open Loyalty uses a webhook subscription pattern. With this pattern, you define the event and destination for that event. Additionally, you should add authorization headers to protect yourself from potential fraudulent calls.

AWS Lambda is one of the examples of a destination. It can be literally anything as long as it has a URL and accepts JSON payload over HTTPS (recommended) protocol. Here we used AWS API Gateway to create a URL and pointed it to the AWS Lambda function written in NodeJS that accepts Open Loyalty’s webhook and transforms it to an API call to Bloomreach to trigger configured actions based on this call. 

Don’t forget

Here are some of the crucial parts to consider, like performance, throttling, and security. Using AWS can solve some of them if you want to quickly integrate two systems and leverage existing cloud providers. However, you can use anything like Mule, Zapier or even your own on-premise solutions. 

Security is crucial here: you need to check if the webhook is coming from trusted sources like Open Loyalty by checking authorization headers. The same goes for communication to Bloomreach. Ideally, the code should not contain credentials but should be checked against a secure storage like AWS Secret Manager.

AWS Lambda-Bloomreach API calls

AWS Lambda sends secure API calls to Bloomreach along with API User and API Secret and correct payload

Payload

{
    "customer_ids": {
        "registered": "john.doe@example.com"
    },
    "properties": {
        "tier_id": "1bc6adfc-d9a1-4b87-b371-da1468db602d",
        "tier_name": "Gold",
        "tenant_code": "Germany",
        "levelMove": "up",
    },
    "event_type": "loyalty_challenge"
}

Finally, Bloomreach does the job based on the event. It can be anything from adding to a Segment to sending a notification to the end user, whether a push notification, SMS or just an e-mail congratulating for gaining a higher tier in the loyalty program.

It’s important to recognize this achievement and maintain a loyal relationship with your customers. 

Where to go from here?

Remember that this is a simple example of how to integrate two systems in under 30 minutes and achieve business goals.

While we can’t go into further technical details about our real-life implementation, here are our recommended next steps:

• To increase the security of your integration, consider secret managers or vaults like AWS Secret Manager;
• Things can go south, so think about how to increase the resilience of your integration. Adding queues like AWS SQS and retry patterns is a must-have if you think about the high reliability of your integration;
• The integration layer can become quite complex quickly. So think about automation, using Infrastructure as a Code (IaaC), and proper testing;
• Serverless functions are a great way to start but can be not enough if you need more complex integration requiring advanced workflows, dependencies, or logical units. Then AWS Simple Workflow Service, Zapier, or on-premise solutions like Mule are a way to go. 

Summary and conclusion

Being able to help our partner achieve their business goals was very rewarding, and we couldn’t pass up the opportunity to share such an interesting use case.

As mentioned, the implementation shown here is only the start – the reality includes many additional steps, from security checks to specific implementations. However, the basis really did take only 30 minutes to code. Thanks to technical expertise and the flexibility of API-first platforms.