Introduction

Annex Cloud offers Customers the possibility to define additional data attributes for the following objects within the loyalty configuration:

• Actions
• Badges
• Orders
• Products
• Rewards
• Stores
• Users
• Campaigns

Once defined, these extended attributes allow additional data to be provided in the API requests and/or Data Feeds that are processed by Annex Cloud. The additional values for each object are stored within the database and these additional data points can then be used within the configuration in the ADR, e.g. Tiers, Campaigns, Segmentation etc., to give a more precise and customized level of control. This information is also made available in the various reports and Data Feed exports which are produced as an output from the platform, e.g. the Members Report will include any extended attributes that have been set for the Users.

The extended attributes can be configured within the ADR at any time by clicking on the ‘Products’ tab, then ‘Additional Loyalty Settings’ and then selecting 'Extended Attributes'. This allows new functionality and features to be implemented by the Customer whenever required.

In this document, we will focus on how to use extended User attributes via the Annex Cloud User API.

Process for Using Extended User Attributes via the API

To use extended attributes, follow these steps:

STEP 1: Define the Extended User Attributes at the Site Level

Before data can be stored in extended attributes, you must first define them at the site level within the Annex Cloud admin portal. For instructions on adding extended attributes, refer to the following link: Extended Attributes

In the example below, you can see that three additional user attributes have been added at the site level:

STEP 2: Use Extended Attributes in the User API Requests

Once you have define the extended attributes within the ADR, you can start to utilize these attributes in order to provide more information about members when they are first added to the loyalty program or when they update their user profile over time

In the body of the createUser and/or updateUser request, the extendedAttribute object should be populated with the key/value pairs as required. For example, in the image below, the request body contains the extended attribute Region, with the value set to USA. Once this is sent and processed successfully, the response confirms this attribute value has been assigned to the member:

This can also be verified in the member report within the ADR:

You cannot use extended attributes that have not yet been defined at the site level. If you attempt to add a non-existent extended attribute that is not present at the site level, the system will process the request but the response will indicate that the extended attribute value is not stored. The screenshot below demonstrates an example where an extended attribute Country was included in the request body but this was not configured within the ADR at the site level. Despite a successful response where the member was added to the loyalty program, no extended attribute was recorded in this case.

Where multiple extended attributes have been defined, it is important to note that these should be included as key/value pairs that are comma separated within the extendedAttribute object. Please see the example below:

{
    "id": "JD25@domain.com",
    "firstName": "James",
    "lastName": "Dee",
    "optInStatus": "YES",
    "extendedAttribute": 
        {
        "usertype": "VIP",
        "Region": "USA",
        "T-Shirt-Size": "M"
        }
}