Introduction

We, at Annex Cloud, are a leading software company specializing in delivering comprehensive customer loyalty solutions, referral marketing platforms, and customer retention tools. Our core offering, the Loyalty Experience Platform, is a robust suite of cloud-based software designed to help businesses cultivate and nurture customer loyalty. Through our platform, companies can effectively manage loyalty programs, incentivize repeat purchases, and personalize customer experiences to foster long-term engagement and brand loyalty.

In addition to our Loyalty Experience Platform, we also provide an Email Service Provider (ESP) solution, enabling businesses to integrate email marketing strategies into their customer engagement efforts. Our ESP empowers companies to deliver targeted and personalized email campaigns, leveraging customer data to drive conversions, enhance brand awareness, and strengthen relationships with their audience.

Overall, our innovative suite of solutions equips businesses across various industries, including retail, e-commerce, hospitality, and consumer goods, with the tools necessary to build enduring customer relationships, drive customer retention, and ultimately achieve business growth.

Purpose

The purpose of this document is to outline the process of integrating Annex Cloud's Loyalty Experience Platform with Dutchie POS, specifically focusing on pushing loyalty data and events based on the workflows created within ESP/Dutchie POS. This integration aims to streamline the exchange of customer data between the Loyalty Experience Platform and Dutchie POS, enabling businesses to leverage loyalty insights and engagement events to enhance their email marketing strategies effectively. By integrating these two platforms, businesses can create more targeted and personalized email campaigns, drive customer engagement, and maximize the impact of their loyalty programs on overall customer retention and brand loyalty.

High-Level Design (HLD)

Revision History

Prerequisites for Installation 

• The prerequisite sample values have been provided below. These are provided by Annex Cloud.

Loyalty Program Version

• Version v3 of the platform supports the integration with the Dutchie POS ESP Loyalty program.

Configuration Steps

• Log in to the Social Annex admin site: https://admin.socialannex.com.
• Navigate to Product >> Pre-Built Integrations >> Dutchie.
• Click Go under the Dutchie tile to show the list of created templates.
  
• A list of all templates is shown in the new window, which are created in the Annex Cloud ADR.
  
• Click on the Add New button and add a new store to the template.
  
• You can edit the existing stores of the template using the Edit button:
  

Integration Flow

Installation Steps at the Platform

Staging path: https://api.socialannex.com/dutchiepos/DutchiePOS.php

Production path: https://api.socialannex.com/dutchiepos/DutchiePOS.php

Example: 

Site Id: 153552360 

Loyalty Token: MIBwD71oRiq1RmUXc7v3aNFlOsmbHHXi 

And Encrypt with Base 64 Encode: 

Encoded Auth Key: MTUzNTUyMzYwOk1JQndENzFvUmlxMVJtVVhjN3YzYU5GbE9zbWJISFhp 

Installations of Loyalty Program 

List of Use Cases setup: 

1. Create Customer 
2. Register Customer (from Dutchie POS - AC)
3. Register Customer (from AC- Dutchie POS)
4. Update Customer 
5. Check-In 
6. Get Balance 
7. Get Transaction Balance 
8. Adjust 
9. Redeem 
10. Checkout
11. Return Items 
12. Void Transactions

List of Endpoints to be configured at Dutchie POS:

Create Customer 

• Login to the Dutchie POS system on your device.
• Click the Create Guest button on the main dashboard.
  
• After confirming that all the information is correct, click the Create button. This action will submit the form and create a new guest member in the Dutchie POS system.
  
• After completing these steps, the guest you've created will be visible in the Member Report section within the Annex Cloud ADR.
  

Development (Dev-Pre-Production): 

Production: 

JSON Payload:

{ 
  "customIdentifier": null, 
  "customerId": 538805, 
  "emailAddress": "ac.test40@annex.com", 
  "externalId": "", 
  "firstName": "Ac", 
  "lastName": "Test", 
  "mmjId": null, 
  "dateOfBirth": "1990-03-02T18:30:00", 
  "phoneNumber": "1234567890", 
  "locationIdentifier": null, 
  "locationName": "123", 
  "locId": 2343, 
  "customerType": "Recreational", 
  "isMedical": false 
} 
Success Response- 
{ 
    "success": true, 
    "returnCode": 0, 
    "message": "User Added successfully." 
} 
Failed Response (If Occour)- 
{ 
    "success": false, 
    "returnCode": 0,     
      "message": "Data already exists" 
}

Update Customer

• Login to the Dutchie POS system on your device.
• Click the Edit Profile button on the main dashboard.
  
• After confirming that all the information is correct, click the Save button to save the changes.
  
• After completing these steps, the guest you've created will be visible in the Member Report section within the Annex Cloud ADR.
  

Development (Dev-Pre-Production): 

Production:

JSON Payload:

{ 
  "customIdentifier": null, 
  "customerId": 538805, 
  "emailAddress": "AC.TEST40@ANNEX.COM", 
  "externalId": "", 
  "firstName": "Ac", 
  "lastName": "Test40", 
  "mmjId": null, 
  "dateOfBirth": "1990-03-02T00:00:00", 
  "phoneNumber": "1234567890", 
  "locationIdentifier": null, 
  "locationName": "123", 
  "locId": 2343, 
  "customerType": "Recreational", 
  "isMedical": false 
} 
Success Response- 
{ 
    "success": true, 
    "returnCode": 0, 
    "message": "User Updated successfully." 
}  
Failed Response- 
{ 
    "success": false, 
    "returnCode": 0, 
    "message": "No data found" 
}

Register Customer (from Dutchie POS - AC) 

• Login to the Dutchie POS system on your device.
• Click the Create Guest button on the main dashboard.
  
• After confirming that all the information is correct, click the Create button. This action will submit the form and create a new guest member in the Dutchie POS system.
  
• After completing these steps, the guest you've created will be visible in the Member Report section within the Annex Cloud ADR.
  

Development (Dev-Pre-Production):

Production:

JSON Payload:

{ 
  "customIdentifier": null, 
  "customerId": 538805, 
  "emailAddress": "ac.test40@annex.com", 
  "externalId": "", 
  "firstName": "Ac", 
  "lastName": "Test", 
  "mmjId": null, 
  "dateOfBirth": "1990-03-02T18:30:00", 
  "phoneNumber": "1234567890", 
  "locationIdentifier": null, 
  "locationName": "123", 
  "locId": 2343, 
  "customerType": "Recreational", 
  "isMedical": false 
} 
Success Response- 
{ 
    "success": true, 
    "returnCode": 0, 
    "message": "User Added successfully." 
} 
Failed Response- 
{ 
    "success": false, 
    "returnCode": 0, 
    "message": "Data already exists." 
}

Register Customer (from AC - Dutchie POS)

• Log in to the Social Annex admin site: https://admin.socialannex.com.
• Navigate to Report >> Member.
• Click Go under the Member tile.
  
• After clicking the Go button under the Member tile, the window below displays:
  
•  Click Add New Member to initiate the process of adding a new member.
  
• After confirming that all the information is correct, click the Save button.
  
• The newly created member will be visible in the members list.
  

Note: A cron job set up on regular intervals by AC ensures real-time data synchronization between AC and Dutchie POS.

Check-in 

• Use the search function to find the member you want to check in and select their profile from the search results. Within the member's profile, click the Check-In button to initiate the check-in process for the member. 
  
• After completing these steps, the Opt-In Status will be displayed as Yes in the Member Report section within the AC ADR.
  

Development (Dev-Pre-Production):

Production: 

JSON Payload:

{ 
  "customIdentifier": null, 
  "customerId": 538805, 
  "emailAddress": "AC.TEST40@ANNEX.COM", 
  "externalId": "", 
  "firstName": "Ac", 
  "lastName": "Test40", 
  "mmjId": null, 
  "dateOfBirth": "1990-03-02T00:00:00", 
  "phoneNumber": "1234567890", 
  "locationIdentifier": null, 
  "locationName": "123", 
  "locId": 2343, 
  "customerType": "Recreational", 
  "isMedical": false 
} 
Success Response- 
{ 
    "success": true, 
    "returnCode": 0, 
    "message": "User Added successfully." 
}  
Failed Response- 
{ 
    "success": false, 
    "returnCode": 0, 
    "message": "Data already exists" 
}

Get Balance 

•  Locate the member tiles within the Dutchie POS interface. Click on the member tile corresponding to the member whose balance and loyalty information you want to view.
  
• Once you've clicked on the member tile, you will be directed to a window that displays detailed information about the member and the member balance.
  

Note: Newly added customers in Dutchie POS will be visually highlighted with a yellow star badge.

Development (Dev-Pre-Production):

Production:

JSON Payload:

{ 
  "customIdentifier": null, 
  "customerId": 538805, 
  "emailAddress": "AC.TEST40@ANNEX.COM", 
  "externalId": "", 
  "firstName": "Ac", 
  "lastName": "Test40", 
  "mmjId": null, 
  "dateOfBirth": "1990-03-02T00:00:00", 
  "phoneNumber": "1234567890", 
  "locationIdentifier": null, 
  "locationName": "123", 
  "locId": 2343, 
  "customerType": "Recreational", 
  "isMedical": false 
} 
Success Response- 
{ 
    "points": 100, 
    "dollarValue": 100, 
    "pointsPerDollar": 1, 
    "success": true, 
    "returnCode": 0, 
    "message": "User Balance." 
} 
Failed Response- 
{ 
    "success": false, 
    "returnCode": 0, 
    "message": "No data found" 
}

Get Transaction Balance 

Development (Dev-Pre-Production):

Production:

JSON Payload:

{ 
  "customerId": 1234, 
  "firstName": "Ac", 
  "lastName": "Test40", 
  "dateOfBirth": "01/01/1900", 
  "emailAddress": "ac.test40@annex.com", 
  "phoneNumber": "1234567890", 
  "mmjId": "id", 
  "customIdentifier": "custom id", 
  "externalId": "external id", 
  "locId": 2343, 
  "locationIdentifier": "operator provided string", 
  "locationName": "location name", 
  "customerType": "Medical", 
  "isMedical": true, 
  "transactionId": 1234 
} 
Success Response- 
{ 
  "success": true, 
  "returnCode": 0, 
  "message": "Get Transaction Balance.", 
  "pointsEarned": 303, 
  "pointsUsed": 100, 
  "pointsAvailable": 203, 
  "dollarsEarned": 303, 
  "dollarsUsed": 100, 
  "dollarssAvailable": 203, 
  "tier": "Tier1" 
} 
Failed Response- 
{ 
    "success": false, 
    "returnCode": 0, 
    "message": "No data found" 
}

Adjust

Development (Dev-Pre-Production):

Production:

JSON Payload:

{ 
  "customerId": 1234, 
  "firstName": "Ac", 
  "lastName": "Test40", 
  "dateOfBirth": "01/01/1900", 
  "emailAddress": "ac.test40@annex.com", 
  "phoneNumber": "123467890", 
  "mmjId": "id", 
  "customIdentifier": "custom id", 
  "externalId": "external id", 
  "locId": 2343, 
  "locationIdentifier": "operator provided string", 
  "locationName": "location name", 
  "adjustmentAmountPointValue": 200.0, 
  "adjustmentAmountDollarValue": 200.0, 
  "adjustingUsername": "user@test.com", 
  "adjustingUserId": 1234, 
  "approvedByUsername": "approver@test.com", 
  "approvedByUserId": 1235, 
  "adjustmentReason": "reason", 
  "customerType": "Medical", 
  "isMedical": true 
} 
 
 
Success Response- 
{ 
  "points": 203, 
  "dollarValue": 203, 
  "pointsPerDollar": 1, 
  "tier": "", 
  "success": true, 
  "returnCode": 0, 
  "message": "Points Adjust." 
} 
Failed Response- 
{ 
    "success": false, 
    "returnCode": 0, 
    "message": "No data found" 
}

Redeem 

• Start by creating an order within the Dutchie POS system. During the order creation process, apply a discount coupon. After the order has been completed and the payment has been processed, Dutchie POS automatically calls the Redeem API. This API is responsible for deducting loyalty points from the customer's account based on the discount applied during the order.
  
• After completing these steps, the Redeem action will be displayed in the All Interaction Report section within the Annex Cloud ADR.
  

Development (Dev-Pre-Production):

Production:

JSON Payload:

{ 
  "transactionId": 1612536, 
  "pointsRedeemed": 100, 
  "dollarsRedeemed": 100, 
  "customIdentifier": null, 
  "customerId": 538805, 
  "emailAddress": "AC.TEST40@ANNEX.COM", 
  "externalId": "", 
  "firstName": "Ac", 
  "lastName": "Test40", 
  "mmjId": null, 
  "dateOfBirth": "1990-03-02T00:00:00", 
  "phoneNumber": "1234567890", 
  "locationIdentifier": null, 
  "locationName": "123", 
  "locId": 2343, 
  "customerType": "Recreational", 
  "isMedical": false 
} 


Success Response- 
{ 
    "success": true, 
    "returnCode": 0, 
    "message": "Points Redeemed." 
} 
Failed Response- 
{ 
    "success": false, 
    "returnCode": 0, 
    "message": "No data found" 
}

Checkout 

• Begin by selecting the member for whom you want to create the order. Click the Create Order button to initiate the order creation process.
  
• After clicking on the Create Order button, you'll be directed to a screen where you can add product items. Click on the Add Items button to access the product list.
  
• From the product list, select the desired product item. Click the Add to Cart button to add the selected product to the order.
  
• You can add a discount on a selected product by clicking the Apply discount.
  
• Select the available discounts and click Apply discount to apply the selected discount one the product.
  
• Once you've added all desired products and applied any discounts, click on the Select Payment Type button to proceed with the payment.
  
• Choose the preferred payment method for the order. After selecting the payment type, click the Pay button to complete the payment process.
  
• Upon successful payment, you'll see a confirmation message indicating Payment successful!.
  
• After completing these steps, the order you've created will be visible in the Order Report section within the Annex Cloud ADR.
  

Development (Dev-Pre-Production):

Production:

JSON Payload:

{
    "transactionId": 1613197, 
    "total": 14.49, 
    "totalTax": 2.49, 
    "subTotal": 15, 
    "totalDiscount": 3, 
    "transactionDateUTC": "2024-03-19T06:28:52.825103Z", 
    "orderSource": null, 
    "items": [ 
        { 
            "category": "Pack", 
            "discount": 3, 
            "productName": "AVO - Forbidden Fruit 1G 7PK", 
            "productSKU": "A7AA48C2E7", 
            "quantity": 1, 
            "tax": 2.49, 
            "total": 15, 
            "productId": 251409 
        } 
    ], 
    "customIdentifier": null, 
    "customerId": 537287, 
    "emailAddress": "ac.test@annexcloud.com", 
    "externalId": "", 
    "firstName": "Ac", 
    "lastName": "Test", 
    "mmjId": null, 
    "dateOfBirth": "2024-03-11T00:00:00", 
    "phoneNumber": "1234567890", 
    "locationIdentifier": null, 
    "locationName": "123", 
    "locId": 2343, 
    "customerType": "Recreational", 
    "isMedical": false 
} 

 
Success Response- 

{ 
    "success": true, 
    "returnCode": 0, 
    "message": "Checkout done", 
    "dollarsEarned": 15 
} 

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

Void Transaction 

•  Access the transaction history section within the Dutchie POS interface. This contains a record of past transactions. Locate the specific transaction you wish to void from the transaction history list. Click on the transaction entry to select it. Look for a menu represented by three dots (...) near the selected transaction entry. After clicking on the three dots, a menu will appear displaying various options related to the transaction. Click on the Void option to initiate the voiding process for the selected transaction.
  
• Once you've selected the Void option, you will see a screen displaying details about voiding the transaction.
  
• To complete the void transaction process, you should enter the required manager PIN, click the Continue button to confirm and finalize the void transaction.
  
• After completing these steps, you can check the member's activities like points redeemed, purchases/returns, etc. from the Member's details dashboard.
  

Development (Dev-Pre-Production):

Production:

JSON Payload:

{ 
    "transactionId": 1613197, 
    "total": -14.49, 
    "totalTax": -2.49, 
    "subTotal": -15, 
    "totalDiscount": -3, 
    "transactionDateUTC": "2024-03-19T02:28:52.827Z", 
    "voidDateUTC": "2024-03-19T08:18:56.3582875Z", 
    "orderSource": null, 
    "items": [ 
        { 
            "category": "Pack", 
            "discount": 3, 
            "productName": "AVO - Forbidden Fruit 1G 7PK", 
            "productSKU": "A7AA48C2E7", 
            "quantity": 1, 
            "tax": 2.49, 
            "total": 15, 
            "productId": 251409 
        } 
    ], 
    "customIdentifier": null, 
    "customerId": 537287, 
    "emailAddress": "ac.test@annexcloud.com", 
    "externalId": "", 
    "firstName": "Ac", 
    "lastName": "Test", 
    "mmjId": null, 
    "dateOfBirth": "2024-03-11T00:00:00", 
    "phoneNumber": "1234567890", 
    "locationIdentifier": null, 
    "locationName": "123", 
    "locId": 2343, 
    "customerType": "Recreational", 
    "isMedical": false 
} 

Success Response- 
{ 
    "success": true, 
    "returnCode": 0, 
    "message": "Return Successfully." 
} 

Failed Response- 
{ 
    "success": false, 
    "returnCode": 0, 
    "message": "No data found." 
}

Return Items 

Development (Dev-Pre-Production):

Production:

JSON Payload:

{ 
    "transactionId": 48789200234691556774, 
    "returnForTransactionId": 48789200234691556774, 
    "total": 44.94, 
    "totalTax": 2.94, 
    "subTotal": 42, 
    "totalDiscount": 0, 
    "transactionDateUTC": "2024-01-19T15:24:48.633Z", 
    "orderSource": null, 
    "customIdentifier": null, 
    "customerId": 14605295, 
    "emailAddress": "MARY.NEUBECK@GTIGROWS.COM", 
    "externalId": "", 
    "firstName": "Mary", 
    "lastName": "Neubeck", 
    "mmjId": null, 
    "dateOfBirth": "1992-08-02T05:00:00", 
    "phoneNumber": "8159536692", 
    "locationIdentifier": null, 
    "locationName": "123", 
    "locId": 1557, 
    "customerType": "Recreational", 
    "isMedical": false, 
    "items": [ 
        {
            "category": "Apparel-Bag-Tote", 
            "discount": 0, 
            "productName": "A(Bag-Tote)-RISE Branded-(Canvas)", 
            "productSKU": "10044957", 
            "quantity": 1, 
            "tax": 0.98, 
            "total": 14, 
            "productId": 485216 
        }, 
        { 
            "category": "Apparel-Bag-Tote", 
            "discount": 0, 
            "productName": "A(Bag-Tote)-RISE Branded-(Canvas)", 
            "productSKU": "10044957", 
            "quantity": 1, 
            "tax": 0.98, 
            "total": 14, 
            "productId": 485216 
        }, 
        {
            "category": "Apparel-Bag-Tote", 
            "discount": 0, 
            "productName": "A(Bag-Tote)-RISE Branded-(Canvas)", 
            "productSKU": "10044957", 
            "quantity": 1, 
            "tax": 0.98, 
            "total": 14, 
            "productId": 485216 
        } 
    ] 
     
} 

Success Response- 
{ 
    "success": true, 
    "returnCode": 0, 
    "message": "Return Successfully." 
}

Functions (for ESP) 

This is not ESP. 

Configurable Fields List (for ESP)

This is not ESP. 

Installations of Refer-a-Friend (RAF) 

List of all possible use cases setup:

Use Cases: 

1. Create Customer 
2. Register Customer 
3. Update Customer 
4. Check-In 
5. Get Balance 
6. Get Transaction Balance 
7. Adjust 
8. Redeem 
9. Checkout 
10. Return Items 
11.  Void Transactions 

Instructions for Resolving the Run-Time Errors 

Adjust Real-Time Response from Dutchie POS

• Analyze the current real-time response mechanism from Dutchie POS. Identify any issues causing runtime errors or delays in response. Optimize the communication process to ensure quicker and more efficient responses.

Obtain Auth Token from Dutchie POS without Bearer

•  Review the authentication mechanism used to obtain an Auth token from Dutchie POS. Ensure that the token retrieval process does not require the Bearer prefix in the authorization header. Adjust the token acquisition process accordingly to match the requirements.

Understand Location ID and Maintain Template ID on the AC ADR

• Gain a clear understanding of the purpose and usage of Location ID and Template ID in the integration with Dutchie POS. Verify that the Location ID and Template ID are correctly mapped and maintained on the AC ADR. Update or synchronize the Location ID and Template ID as necessary to ensure proper functionality.

Create Location ID Matching with the Template ID

• Create new Location IDs that match the corresponding Template IDs required for integration with Dutchie POS. Ensure that each Location ID is accurately associated with its respective Template ID to facilitate seamless communication.

Utilize Authorization Token for Security

• Implement the use of Authorization tokens to authenticate and maintain security in communication with Dutchie POS. Ensure that all requests sent to Dutchie POS include the required Authorization token in the header.

Handle All Possible Conditions for Parameters

• Review and update the code to handle all possible conditions for parameters passed in requests to Dutchie POS. Implement error handling mechanisms to address any unexpected conditions and prevent runtime errors.

Note: If any of the above headers are not applicable to the respective platform, then it shouldn’t be mentioned.

Appendix

• List of Definitions