Creating and managing user groups is a structured process that covers group creation, membership configuration, and lifecycle management. The following steps guide you through each stage. There are two types of groups: friends-and-family groups and business groups.

Creating a friends and family group

A friends and family group is a simple user group with a simple hierarchy: a primary member with administrator privileges and secondary members with no permissions or permissions to redeem or transfer points.

Step 1: Creating a group

Start by creating a user group and defining basic details, such as the user group name, external identifier, and maximum group size. You can also add additional metadata using extended fields.

To create a user group, use the POST /v2/userGroup2 API to create a user group and define the following:

Example request body:

{
  "externalId": "family_ug_1",
  "groupName": "FamilyGroup1",
  "maxGroupSize": 6,
  "extendedFields": {
    "ug_status": "Active",
    "group_avatar_url": "https://example.com/avatar.png",
    "ug_registration_date": "2025-11-10T15:10:00Z"
  }
}

You have created the group entity and are now ready to update its details or begin adding members.

Step 2: Adding members and defining permissions

Once you have created a user group, you can add a primary member and secondary members and define permissions for the members.

Adding a member

To add members to a user group, use the POST /v2/userGroup2/join API. Set the primaryMember value to true for the primary member. You can also define permissions to allow or block users from transferring and redeeming points.

The payload structure comprises the following:

Example request:

[
  {
    "userId": 564662499,
    "primaryMember": false,
    "permissions": [
      "allow_points_redemption",
      "allow_points_transfer"
    ],
    "defaultGroup": true,
    "active": true
  }
]

Assigning permissions to a member

Permissions can be set at join time using the permissions array in the /v2/userGroup2/join payload.

To remove a secondary member from the group, see Removing a secondary member.

You can also create a more structured setup for corporate use cases.

Creating a business group

A business group is a structured user group with a defined hierarchy. Unlike a friends-and-family group, it can comprise multiple roles with varying permissions, and members are assigned to roles based on their position in the organisational structure.

Setting up a business group is a four-step process:

• Define the hierarchy
• Associate customers with the heirarchy
• Create the group entity
• Add members to the user group.

Step 1: Create a hierarchy

Define the hierarchy structure before creating any group or associating any customers. See Create a hierarchy for more information.

Step 2: Associate the hierarchy with a customer

Once the hierarchy is defined, associate it with a new or existing customer using the associationDetails object in the associte customer create or update API call.

Example request body:

{
  "profiles": [
    {
      "identifiers": [
        {
          "type": "mobile",
          "value": "9781027293"
        }
      ]
    }
  ],
  "associationDetails": {
    "hierarchyCode": "SIL0101",
    "roleCode": "Drivers",
    "fleetCompany": {
      "name": "X Company",
      "hierarchyDefinitionCode": "SIL0101",
      "externalId": "c_123"
    }
  }
}

Step 3: Create a user group and add members

Follow the steps described in Creating a friends and family group:

• Create the group entity using POST /v2/userGroup2 and
• Add members using POST /v2/userGroup2/join.

Once a group is created and its members are added, you can perform ongoing membership management such as transfers and removals.

Managing members

Once a group is created and populated, you can manage membership through dedicated API endpoints. This section covers assigning permissions, removing members, and handling ownership changes.

Removing a secondary member

To remove a secondary member, use DELETE /v2/userGroup2/{groupId}/leave (see Remove group member). Identify the member using the identifierName and identifierValue query parameters.

Example request:

curl -L -X DELETE 'https://eu.api.capillarytech.com/v2/userGroup2/3952525/leave
  ?source=INSTORE
  &identifierName=mobile
  &identifierValue=918988123462' \
-H 'Authorization: Basic {token}'

📘

Note:

Only secondary members can be removed this way. Removing the primary member has a different outcome. See Deleting a group.

Transferring members between groups

Merging two groups into one is not supported. However, you can move specific members between groups using the transfer API. This is useful when reorganising group structures or consolidating members after a group is dissolved.

Use POST /v2/userGroup2/transfer (see Transfer group member) and provide the source group ID (leaveGroupId), the destination group ID (joinGroupId), and a list of member user IDs to move.

Example request:

curl -L 'https://eu.api.capillarytech.com/v2/userGroup2/transfer' \
-d '{
  "leaveGroupId": "3917591",
  "joinGroupId": "3916144",
  "userIds": [564829146, 564709342]
}'

📘

Note:

Points are not transferred automatically when members move between groups. Handle point transfers separately before or after initiating the member transfer.

Transaction returns after group updates

When a member makes a purchase as part of a group and then changes groups before returning the item, the return transaction may be blocked by default. This is because the system validates the member's current group context against the original transaction's group context.

You can override this behavior to allow returns even after the member has moved to a different group. This is particularly relevant in fleet or B2B programs where member transfers between groups are common.

To do this, enable the CONF_ALLOW_TRANSACTION_RETURN_AFTER_GROUP_TRANSITION flag by raising a JIRA ticket to the Capillary product support team.

📘

Note:

Enabling this flag can result in negative group wallet balances. When a return is processed after the original points have already been redeemed, the reversal pushes the group balance below zero.

When a group is no longer needed, it can be deleted through the API.

Deleting a group

To delete a user group, use DELETE /v2/userGroup2 (see Delete user group) with the group's id or externalId as query parameters.

Example request:

curl -L -X DELETE 'https://eu.api.capillarytech.com/v2/userGroup2?id=3916904&externalId=uat_ug_10_delete_1' \
-H 'Authorization: Basic {token}'

By default, a user group is deactivated when the primary member leaves. All members lose access to the shared wallet, and the group can no longer be managed or searched in Member Care. You can override this behavior to keep the group active even after the primary member exits. This is useful when the group's operations should continue independently of the original owner.

Example: A fleet owner decides to leave the program. Rather than immediately dissolving the fleet group, the brand enables this flag to keep the group active to allow secondary members to earn and redeem group points.

To do this, enable the CONF_DISABLE_GROUP_DEACTIVATION_ON_PRIMARY_MEMBER_EXIT flag by raising a JIRA ticket to the Capillary product support team.

📘

Note:

When enabled, the group remains active but has no primary member. It is not possible to add a new primary member or reassign primary membership to an existing member once the primary member has exited the user group. Points in the group wallet remain accessible to members with redemption permissions during this period.