Hierarchy Management

Updated at May 21st, 2025

Introduction

When you think of a loyalty program, you may typically picture a single loyalty member earning points and rewards for engaging with a brand through purchases and other brand-related activities. However, with Annex Cloud, you can offer members the chance to participate and engage in loyalty programs at the group level, giving members the chance to accrue and use points as a group. Annex Cloud’s Hierarchy Management feature and reports will allow you to quickly create group guidelines, manage groups, and track group data.

This document will review the function of hierarchy management groups, how to establish group guidelines, how to create and update groups, and how to retrieve group data.

Group Points

There are two rule sets to choose from when configuring how loyalty points will be shared among groups.

Manual Donation: With manual donation, when a group member completes an action for which they earn points, these points are not counted toward the group total until the member elects to transfer them to the group. For instance, if member A has 200 points and chooses to manually add 100 points to the group, 100 of their points will be added to the group and 100 points will still be in their personal account.
Auto-Transfer: The second type is where the group auto-transfer rule is in place, wherein the points that each group member earns are automatically added to the group's account. In other words, if member A earns 200 points, the group account will automatically receive all 200 points.

Redeeming Group Points

Unlike individual loyalty points, group points are shared among group members. Therefore, it is important to distinguish how points are able to be redeemed. This is determined when establishing the group guidelines.

Group Roles

There are two roles that shoppers in a group can inhabit, owner and member. The descriptions below describe how the roles are distinguished.

Owner: A group owner has the ability to add and remove members from the group. The person who creates the group will automatically have owner status.

The group owner may also be the only group member allowed to redeem group points or dissolve the group if determined in group guidelines upon configuration.

Member: Members do not have the ability to add and remove members from the group.

Only registered loyalty members will be able to create or join a group.

Hierarchy Management Settings

The hierarchy management settings enable the customization of group rules and permissions to match the loyalty program's structure. The program administrator establishes rules at a global level, while group owners can adjust permissions based on the specific purpose of creating the group.

Navigation: Products > Hierarchy Management > Hierarchy Management Settings

Click GO on the Hierarchy Management button to navigate to the Hierarchy Management Settings page.

Hierarchy Management Settings consist of the following options:

Enable Group Level Permission

Enabling this feature allows the group owner to establish specific rules for group members, which can vary across different groups. Currently, two rules are in place: the group points redemption rule and the automatic transfer of points to the group. The rules set by the group owner will override the global rules. If this feature is turned ON, group-level rules may differ from one group to another.

Enable Auto Transfer Points to Group

If this flag is ON, whenever a member of the group earns points for performing a point-awarding loyalty action, the points will automatically go into the group bank instead of their individual account. If the flag is turned OFF, group members can manually donate their points to the group.

Enable Auto Transfer Available Points to Group upon Joining

This feature allows you to set a condition for transferring the points members earned prior to joining the group immediately upon joining. When this flag is ON, all member points are transferred to the group.

When loyalty members have points before joining the group and the Enable Auto Transfer Points to Group flag is turned ON at the time of joining the group, all the member's points will be automatically transferred to the group account. If the flag is turned OFF, members will have the choice to manually donate their points to the group.

Enable Auto Group Points Redemption

This flag allows the group owner or group members to automatically redeem group points. If this flag is ON, whenever a member of the group redeems the points, the group points will be considered for the redemption and the group points will be debited automatically.

If this flag is OFF, whenever a member of the group redeems the points, their individual points will be considered for the redemption and points from the individual account will be debited. In this case, if the member of the group wants to redeem group points instead of individual points, the group ID will be required in the API request payload.

Group Points Redemption Rule

There are two options available for this feature: the group owner can redeem the group points, or all group members can redeem the points.

If you choose the Group Owners Only option from the drop-down list, only the group owner will have the authority to redeem group points. If you select All Group Members, then all group members will have the authority to redeem the group points.

Group Invitation Acceptance Required

If this flag is enabled when the group is created, whenever the group owner adds a loyalty member to the group, a group invitation is sent to the member which can be viewed using the API method or be viewed by program administrators within the Hierarchy Management Report under the Action column. The member must accept the invitation before joining the group. If they decline the invitation, they will not be added to the group. By default, this flag is ON.

If the Group Invitation Acceptance Required flag is turned OFF, members will be automatically added to the group.

Restrict Members to Leave Group

This option enables the group owner to restrict members from leaving the group. When the member wishes to leave, an automatic group leave request is sent to the group owner. The member can only exit the group if the group owner approves the request.

If the Restrict Members to Leave Group flag is OFF, members can leave the group at any time without needing approval.

Group Dissolve Permissions

This option allows the program administrator to set the criteria for who is eligible to delete the group. If the administrator selects Group Owners from the drop-down list, only the group owner is eligible to delete the group. If the administrator selects All Group Members, then all group members are eligible to delete the group.

Points Distribution Rules on Group Dissolution

When deactivating an existing group, the program administrator has the option to set a rule for distributing the existing points of the group. There are two options available:

Transfer who Dissolved the Group: In this case, all the group points are transferred to the member who dissolved the group.
Transfer Equal Points to All Group Members: In this case, all the group points are distributed equally among all group members. For example, if a group consisting of 10 members has 100 points and the group is dissolved, 10 points will be transferred to each group member.

Enable Maximum Member Limit Per Group

The program administrator has the ability to set the size of the group. If this option is enabled, you can specify the maximum number of members allowed to join a group. For instance, if you want to limit the group to 10 members, you should enter 10 in the Enter Number Of Members box as shown below. The number of members must be greater than zero; otherwise, the settings will not be allowed to update. This feature allows for better group management and allocation of roles by imposing a limit on the group size.

Once all settings in the hierarchy management group have been configured, click Update to save the changes.

Creating Groups

There are two methods to create a hierarchy management group within the loyalty program. Groups can be created through the Hierarchy Management Report and via API.

Creating a Group via Hierarchy Management Report

To create a group, you need to visit the hierarchy management report page and focus on the top right of the page. Click Create Group located next to Export. This will open the Create New Group pop-up where you can enter the required information to create the group.

Refer: Hierarchy Management Report

Creating a Group via Hierarchy Management API

The other method for creating the hierarchy management group is through the API. A group can be created using the POST: /groups method.

Refer:API Documentation

A member can only be part of one group at a time. For example, If a member is currently in GROUP A and wants to join GROUP B, they must first leave GROUP A. It is not possible for a member to be part of more than one group simultaneously.

Action IDs

The following list contains the action IDs associated with Hierarchy Management.

182 - HM Group Joining
183 - HM Group Member Leave
184 - HM Group Member Remove
185 - HM Group Dissolve
186 - Manual Group Points Transfer