Introduction

Annex Cloud is a loyalty program solution provider. Annex Cloud offers a complete loyalty package to the platform. One View Commerce is a Point of Sale (POS) platform which offers compatibility with Annex’s loyalty program.

Purpose

This document gives details of integration of Annex Cloud loyalty program with One View Commerce (OVC) POS. The loyalty program is implemented with the use if middleware of AWS. 

High Level Design (HLD)

Revision History 

Prerequisites for Installation

• Client Name: To be mentioned once client has been onboarded.
• Site ID: Site is created by customization team with specific setup.  
• Access Token: Every new site has a different access token.
• Auth Key: To be provided separately. 

Loyalty Program Version 

The integration supports OVC’s 7.4.0-alpha.132 version with Annex’s loyalty API version V3. 

Configuration Steps 

• Define the Annex Cloud loyalty endpoints which will be configured at OVC. This enables Annex Cloud’s loyalty program with OVC.
• Annex Cloud created endpoints to provide requested data to OVC POS system.
• OVC POS system sends us a request using GET, PATCH and POST methods. Annex Cloud provides data using AC REST APIs.
• OVC POS tech team configure AC endpoints at their end with authorization tokens. 

List of Endpoints to be configured at OVC:

Create Customer

Json Payload:

{
    "firstName": "Ac",
    "lastName": "Test3",
    "email": "ac.test3@annex.com",
    "address": {
        "line1": "adas", 
        "line2": "asdad",
        "town": "asdad", 
        "stateProvince": "MA", 
        "postalCode": "02169", 
        "country": "United States"
    }, 
    "emailOptin": false 
} 

 Successful Response- 

{ 
    "success": true,
    "returnCode": 0,
    "message": "User Added successfully."
}

 Failed Response- 

{
    "success": false,
    "returnCode": 0,
      "message": "Data already exists"
}

Update Customer 

Json Payload- 

{
  "firstName": "Ac",
  "lastName": "Test3", 
  "email": "ac.test3@annex.com",
  "address": {
    "line1": "adas",
    "line2": "asdad",
    "town": "asdad",
    "stateProvince": "MA",
    "postalCode": "02169",
    "country": "United States"
  },
  "emailOptin": false
}

Successful Response-  

{
    "id": "ac.test3@annex.com",
    "firstName": "Ac3",
    "lastName": "Test3",
    "email": "ac.test3@annex.com",
    "loyaltyTier": "Silver",
    "Birthday": "-00011130",
    "optInStatus": true,
    "loyaltyCustomerSince": "20240419",
    "availablePoints": 450,
    "pendingPoints": 0,
    "rewardsAvailable": 2,
    "lifetimePoints": 1700,
    "rewardsClaimed": 2,
    "spendToNextTier": 50,
    "pointsToNextReward": 150,
    "Rewards": [
        {
            "rewardId": "39974",
            "displayText": "$5",
            "rewardType": "1",
            "creditRequired": "150",
            "rewardValue": "5.00",
            "eligible": true,
            "rewardLimit": 0,
            "limitPeriod": "Anniversary Year",
            "redeemCount": 2,
            "remainingCount": 0
        },
        { 
            "rewardId": "39975",
            "displayText": "$10",
            "rewardType": "1",
            "creditRequired": "300",
            "rewardValue": "10.00",
            "eligible": true,
            "rewardLimit": 0,
            "limitPeriod": "Anniversary Year",
            "redeemCount": 2,
            "remainingCount": 0
        },
        {
            "rewardId": "39976",
            "displayText": "$15",
            "rewardType": "1",
            "creditRequired": "600",
            "rewardValue": "20.00",
            "eligible": false,
            "rewardLimit": 0,
            "limitPeriod": "Anniversary Year",
            "redeemCount": 0,
            "remainingCount": 0
        },
        {
            "rewardId": "39977",
            "displayText": "$30",
            "rewardType": "1",
            "creditRequired": "900",
            "rewardValue": "30.00",
            "eligible": false,
            "rewardLimit": 0,
            "limitPeriod": "Anniversary Year",
            "redeemCount": 0,
            "remainingCount": 0
        },
        {
            "rewardId": "39978",
            "displayText": "$50",
            "rewardType": "1",
            "creditRequired": "1500",
            "rewardValue": "50.00",
            "eligible": false,
            "rewardLimit": 0,
            "limitPeriod": "Anniversary Year",
            "redeemCount": 0,
            "remainingCount": 0
        }
    ],
    "userActivity": {
        "pages": 1,
        "currentPage": 1,
        "totalActivityCount": 10,
        "activityDetails": [
            {
                "actionId": "107",
                "displayText": "$10-Reward Redeem",
                "displayPoints": -300,
                "activityDate": "20240502"
            },
            {
                "actionId": "109",
                "displayText": "Purchase",
                "displayPoints": 500,
                "activityDate": "20240502"
            },
            {
                "actionId": "107",
                "displayText": "$10-Reward Redeem",
                "displayPoints": -300,
                "activityDate": "20240502"
            },
            {
                "actionId": "100",
                "displayText": "Manual Credit/Debit",
                "displayPoints": 400,
                "activityDate": "20240502"
            },
            {
                "actionId": "107",
                "displayText": "$5-Reward Redeem",
                "displayPoints": -150,
                "activityDate": "20240419"
            },
            {
                "actionId": "100",
                "displayText": "Manual Credit/Debit",
                "displayPoints": 150,
                "activityDate": "20240419"
            },
            {
                "actionId": "154",
                "displayText": "Redemption Credit",
                "displayPoints": 150,
                "activityDate": "20240419"
            },
            {
                "actionId": "148",
                "displayText": "Return",
                "displayPoints": -350,
                "activityDate": "20240419"
            },
            {
                "actionId": "107",
                "displayText": "$5-Reward Redeem",
                "displayPoints": -150,
                "activityDate": "20240419"
            },
            {
                "actionId": "109",
                "displayText": "Purchase",
                "displayPoints": 500,
                "activityDate": "20240419"
            }
        ]
    },
    "usedRewards": {
        "pages": 1,
        "currentPage": 1,
        "rewards": [
            {
                "rewardId": "39975",
                "displayText": "$10",
                "rewardType": "1",
                "creditRequired": "0",
                "rewardValue": "10",
                "eligible": true,
                "rewardLimit": 0,
                "remainingCount": 0
            },
            {
                "rewardId": "39975",
                "displayText": "$10",
                "rewardType": "1",
                "creditRequired": "0",
                "rewardValue": "10",
                "eligible": true,
                "rewardLimit": 0,
                "remainingCount": 0
            },
            {
                "rewardId": "39974",
                "displayText": "$5",
                "rewardType": "1",
                "creditRequired": "0",
                "rewardValue": "5",
                "eligible": true,
                "rewardLimit": 0,
                "remainingCount": 0
            },
            {
                "rewardId": "39974",
                "displayText": "$5",
                "rewardType": "1",
                "creditRequired": "0",
                "rewardValue": "5",
                "eligible": true,
                "rewardLimit": 0,
                "remainingCount": 0
            }
        ]
    }
}

Failed Response- 

{
    "success": false,
    "returnCode": 0,
    "message": "No data found"
}

Order

• The Order OVC uses an AWS SQS message queue. Annex Cloud can fetch the SQS message queue using the AWS PHP SDK library and place the orders into the AC ADR using the CRON mechanism.
• For now, CRON runs every one minute or the order data can be captured by AC using a lambda function, this function is set at AC AWS instance.

Return Order

• For return order OVC use an AWS SQS message queue, Annex Cloud can fetch the SQS message queue using the AWS PHP SDK library and place the return orders into the AC ADR using the CRON mechanism. 
• For now, CRON runs every one minute or the order data can be captured by AC using a lambda function, this function is set at AC AWS instance.

Installation Steps at the Platform 

Provide both a staging path and production path. (Samples of a staging path and production for better understanding). 

• Annex Cloud has created the authorization key to access AC Loyalty APIs. 
• The authorization key is the combination of the site ID and loyalty token.

Example: 

Site Id: XXXXXXXX (Annex Cloud will provide.) 

Loyalty Token: XXXXXXXX (Annex Cloud will provide.) 

And encrypt with base 64 encode.

Encoded auth key: XXXXXXXXXX 

Installations of loyalty program 

OVC support the following set of use cases 

1. Create customer from OVC to AC. 
2. Update customer from AC to OVC 
3. Get customer- Loyalty identification. 
4. Order- Earn and burn points 
5. Return order- Deduct points 

List of APIs/Data Push/Setting up Trigger 

10.1. Create Customer 

On OVC POS- 

• Once logged in to OVC POS platform you can see the Customers option on the left side of the screen.

• Click on the Create Customer icon.

• Fill in the customer information and click Next to submit the form.

• After submitting the form, the customer is created on the OVC platform as well as on the AC ADR.

OVC Customer Profile:

AC ADR Customer Profile: 

• For customer creation Annex Cloud must use the below endpoints and API setup on the AC side.

Json Payload:

{
    "firstName": "John",
    "lastName": "wick",
    "email": " johnwick@annex.com",
    "address": {
        "line1": "adas",
        "line2": "asdad",
        "town": "asdad",
        "stateProvince": "MA",
        "postalCode": "02169",
        "country": "United States"
    },
    "emailOptin": false
}

 Successful Response- 

{
    "success": true,
    "returnCode": 0,
    "message": "User Added successfully."
}

 Failed Response- 

{
    "success": false,
    "returnCode": 0,
      "message": "Data already exists"
}

Update Customer

On OVC POS- 

The customer update setting is currently unavailable, but Annex Cloud has already developed the code to support this functionality.

On AC ADR:

• To update customer information, Annex Cloud uses Annex Cloud APIs, and the endpoints listed below.

Json Payload- 

{
  "firstName": "Ac3",
  "lastName": "Test3",
  "email": "ac.test3@annex.com",
  "address": {
    "line1": "adas",
    "line2": "asdad",
    "town": "asdad",
    "stateProvince": "MA",
    "postalCode": "02169",
    "country": "United States"
  },
  "emailOptin": false
}

 Successful Response- 

{
    "success": true,
    "returnCode": 0,
    "message": "User Updated successfully."
}

Failed Response- 

{
    "success": false,
    "returnCode": 0,
    "message": "No data found"
}

Get Customer Information  

On OVC POS:

• First search for a customer from the OVC UI and click the searched customer’s email.

• You can now view the loyalty balance and reward related info on the profile page.

• To retrieve customer information, Annex Cloud uses the API endpoints listed below.

Json Payload- 

{
  "firstName": "John",
  "lastName": "wick",
  "email": " johnwick@annex.com",
  "address": {
    "line1": "adas",
    "line2": "asdad",
    "town": "asdad",
    "stateProvince": "MA",
    "postalCode": "02169",
    "country": "United States"
  },
  "emailOptin": false
}

Successful Response-  

{
    "id": "johnwick@annex.com",
    "firstName": "John",
    "lastName": "wick",
    "email": "johnwick@annex.com",
    "loyaltyTier": "chartreuse",
    "Birthday": "-00011130",
    "optInStatus": true,
    "loyaltyCustomerSince": "20240715",
    "availablePoints": 1000,
    "pendingPoints": 0,
    "rewardsAvailable": 4,
    "lifetimePoints": 1000,
    "rewardsClaimed": 0,
    "spendToNextTier": 1000,
    "pointsToNextReward": 500,
    "Rewards": [
        {
            "rewardId": "39978",
            "displayText": "50",
            "rewardType": "1",
            "creditRequired": "1500",
            "rewardValue": "50.00",
            "eligible": false,
            "rewardLimit": 0,
            "limitPeriod": "Anniversary Year",
            "redeemCount": 0,
            "remainingCount": 0
        },
        {
            "rewardId": "39977",
            "displayText": "30",
            "rewardType": "1",
            "creditRequired": "900",
            "rewardValue": "30.00",
            "eligible": true,
            "rewardLimit": 0,
            "limitPeriod": "Anniversary Year",
            "redeemCount": 0,
            "remainingCount": 0
        },
        {
            "rewardId": "39976",
            "displayText": "15",
            "rewardType": "1",
            "creditRequired": "600",
            "rewardValue": "20.00",
            "eligible": true,
            "rewardLimit": 0,
            "limitPeriod": "Anniversary Year",
            "redeemCount": 0,
            "remainingCount": 0
        },
        {
            "rewardId": "39975",
            "displayText": "10",
            "rewardType": "1",
            "creditRequired": "300",
            "rewardValue": "10.00",
            "eligible": true,
            "rewardLimit": 0,
            "limitPeriod": "Anniversary Year",
            "redeemCount": 0,
            "remainingCount": 0
        },
        {
            "rewardId": "39974",
            "displayText": "5",
            "rewardType": "1",
            "creditRequired": "150",
            "rewardValue": "5.00",
            "eligible": true,
            "rewardLimit": 0,
            "limitPeriod": "Anniversary Year",
            "redeemCount": 0,
            "remainingCount": 0
        }
    ]
}

 Failed Response- 

{
    "success": false,
    "returnCode": 0,
    "message": "No data found"
}

Order

On OVC POS:

• After selecting the user, there is an option to Add Customer To Cart.

• After adding the customers into the cart, the below screen appears.

• Select a product from the Product Search section, as shown below, where products are selected and added.

• Once the product is added the following screen appears.

• Once Annex Cloud completes the order, the order will appear in the AWS SQS queue system.

•  Click on Poll for messages and the message queue appears.

• For the above AWS SQS queue, Annex Cloud has implemented a CRON job to handle this process using an AWS PHP SDK to create an order on AC ADR. 
• Every one minute the CRON will check the new orders and process them into the AC ADR order section.
• Processed orders will appear in the Annex Cloud platform under Reports>Order Report

Order Return

On OVC POS:  

• For return orders click on Transaction Section.

• All regular orders appear on the Transactions Search pages.

• Click the Return button, check the form below, and select the Return button at the end.

• Click Confirm.

• Select the return product and its information, then click Customer Lookup and add the customer in the return cart section.

• After adding the customer, click on the Refund option to complete the return order. 

• Once the return order is complete, the return order will appear in the AWS SQS queue system.

• And click Poll for messages to obtain the message queue.

• For the above AWS SQS queue, Annex Cloud has written a CRON using an AWS PHP SDK to return an order on AC’s ADR. 
• Every one minute the CRON will check the new orders and process them into the AC ADR order section.
• You can find the order in the Annex Cloud platform under Reports>Order Report by searching via the order ID. You will see the return is reflected within the report.

• The All-Interaction report displays orders and returns.

Use Cases:

Create Customer 

• As a POS user I want to enroll the new customer from POS to the loyalty program so that the customer will benefit from a loyalty program.

Update Customer 

• As an AC site admin user, I want to make changes in customer profile except the unique ID, so that those changes are reflected in OVC POS system. 

Get Customer Information

• As a POS user I want to look-up customers from POS system so that I can identify if the customer is a loyalty member or not. 

Order 

• As a POS user I want to place an order on behalf of a customer so that the customer will be benefited with

1. Redeem the eligible rewards. 
2. Earn loyalty points.

Return Order

• As a POS user I want to return the item or items on behalf of the customer so that:

1. Earned points will be reversed. 
2. Redeemed points will be awarded back (this can be disable based on the requirements). 

Instructions for Resolving the Run Time Errors 

• To adjust real time response getting from OVC POS. 

1. Ensure the AWS PHP SDK version aligns with both application requirements and the server’s PHP version to avoid compatibility issues.
2. Adapt the code to handle cloud-based environments where not all AWS components are visible, incorporating proper error handling and debugging.
3. Collaborate with developers to adjust the logic as needed for seamless integration and test thoroughly to ensure smooth operation.

System and Security Requirements 

•    Using authorization token to maintain security.
•    Added all the possible conditions for all parameters.