Managing Group Members

Group members are the foundation of expense sharing in BillBuddy. This guide covers everything you need to know about managing who’s in your groups and their permissions.

Member Roles and Permissions

BillBuddy has a simple permission model:

Group Creator

The user who created the group has special permissions:

Add new members
Update group details
Delete the group

Group Members

All members (including the creator) can:

Add expenses
View all expenses and balances
Initiate settlements

Currently, only the group creator can add new members. Regular members cannot invite others.

Adding Members to a Group

Navigate to Your Group

Go to the group page where you want to add a member. You must be the group creator to add members.You’ll see an “Add Member” button in the top-right section of the group page.

// Source: Group.jsx:163-164
<Button variant="contained" startIcon={<PersonAddIcon />} onClick={handleAddMember}>
  Add Member
</Button>

Click Add Member

Click the “Add Member” button to navigate to the add member form at /add-member/:groupId.

// Source: Group.jsx:132
const handleAddMember = () => navigate(`/add-member/${id}`);

Enter Member Email

Enter the email address of the person you want to add:

string

required

The email address of the new memberMust be a valid email format. The user must already be registered in BillBuddy.

// Source: AddMember.jsx:95-105
<TextField
  fullWidth
  label="Member Email"
  variant="outlined"
  value={email}
  onChange={(e) => setEmail(e.target.value)}
  margin="normal"
  required
  type="email"
  disabled={loading}
/>

Unlike group creation, adding members to existing groups requires the user to already have a BillBuddy account. If they don’t exist, you’ll see an error: “User not found”.

Submit

Click “Add Member” to add them to the group.The backend will:

Verify you’re the group creator
Find the user by email
Check they’re not already a member
Add them with a starting balance of ₹0
Update their groups list

// Backend: routes/groups.js:194-249
router.post('/:id/members', protect, async (req, res) => {
  const { email } = req.body;
  const group = await Group.findById(req.params.id);
  
  // Check if user is the creator
  if (group.createdBy.toString() !== req.user.id) {
    return res.status(403).json({ 
      message: 'Not authorized to add members to this group' 
    });
  }
  
  // Find user by email
  const userToAdd = await User.findOne({ email });
  if (!userToAdd) {
    return res.status(404).json({ message: 'User not found' });
  }
  
  // Check if already a member
  const isAlreadyMember = group.members.some(
    member => member.user.toString() === userToAdd._id.toString()
  );
  if (isAlreadyMember) {
    return res.status(400).json({ 
      message: 'User is already a member of this group' 
    });
  }
  
  // Add to group
  group.members.push({ user: userToAdd._id, balance: 0 });
  await group.save();
  
  // Add group to user's groups array
  await User.findByIdAndUpdate(userToAdd._id, {
    $push: { groups: group._id }
  });
});

On success, you’ll see a confirmation message and be redirected back to the group page after 1.5 seconds.

// Source: AddMember.jsx:44-48
setSuccess('Member added successfully!');
setEmail('');
setTimeout(() => {
  navigate(`/group/${id}`);
}, 1500);

Viewing Group Members

Members are displayed on the group page as colorful chips showing their current balance:

// Source: Group.jsx:174-183
<Box sx={{ display: 'flex', flexWrap: 'wrap', gap: 1 }}>
  {group.members.map((member) => (
    <Chip
      avatar={<Avatar>{member.user.name[0]}</Avatar>}
      label={`${member.user.name} (₹${balances[member.user._id]?.toFixed(2) || '0.00'})`}
      color={balances[member.user._id] > 0 ? 'success' : 
             balances[member.user._id] < 0 ? 'error' : 'default'}
    />
  ))}
</Box>

Understanding Member Chips

Green Chip
Red Chip
Gray Chip

Positive Balance - This member is owed money

Alice (₹250.00) 🟢

Alice has paid more than her share and should receive ₹250 from other members.

Negative Balance - This member owes money

Bob (-₹125.50) 🔴

Bob owes ₹125.50 to other members who have covered his expenses.

Zero Balance - This member is settled

Charlie (₹0.00) ⚪

Charlie’s expenses are balanced with what they’ve paid.

Member Data Structure

Each member in a group has the following structure:

// Source: models/Group.js:14-24
members: [{
  user: {
    type: mongoose.Schema.Types.ObjectId,
    ref: 'User',
    required: true
  },
  balance: {
    type: Number,
    default: 0
  }
}]

The balance field in the member object is currently not actively used. Instead, balances are calculated dynamically from expenses each time the group is loaded.

Adding Members During Group Creation

You can add multiple members when first creating a group:

// Source: CreateGroup.jsx:37-66
const handleAddMember = () => {
  if (!validateEmail(memberEmail)) {
    setError('Please enter a valid email address');
    return;
  }
  
  if (formData.members.includes(memberEmail)) {
    setError('This member is already added');
    return;
  }
  
  setFormData({
    ...formData,
    members: [...formData.members, memberEmail],
  });
};

const handleRemoveMember = (email) => {
  setFormData({
    ...formData,
    members: formData.members.filter((m) => m !== email),
  });
};

During creation:

You can add unlimited members
Members are displayed as removable chips
Users are auto-created if they don’t exist
At least one member is required

See the Creating Groups guide for more details.

API Request Examples

POST /api/groups/:groupId/members
Authorization: Bearer <token>

{
  "email": "[email protected]"
}

Permission Checks

The backend enforces strict permission checks:

Who can add members?

// Source: routes/groups.js:210-212
if (group.createdBy.toString() !== req.user.id) {
  return res.status(403).json({ 
    message: 'Not authorized to add members to this group' 
  });
}

Only the user who created the group (createdBy) can add new members.

Who can update group details?

// Source: routes/groups.js:122-124
if (group.createdBy.toString() !== req.user.id) {
  return res.status(403).json({ 
    message: 'Not authorized to update this group' 
  });
}

Only the group creator can update the name, description, or member list.

Who can delete a group?

// Source: routes/groups.js:172-174
if (group.createdBy.toString() !== req.user.id) {
  return res.status(403).json({ 
    message: 'Not authorized to delete this group' 
  });
}

Only the group creator can delete the group.

Who can view group details?

// Source: routes/groups.js:93-98
const isMember = group.members.some(
  member => member.user._id.toString() === req.user.id
);

if (!isMember) {
  return res.status(403).json({ 
    message: 'Not authorized to access this group' 
  });
}

Any member of the group can view its details, expenses, and balances.

Removing Members

The current implementation does not support removing individual members from a group through the UI or dedicated API endpoint.

To remove members, you would need to:

Use the group update endpoint (PUT /api/groups/:id) to replace the entire member list
Manually update the database
Delete and recreate the group

This is a potential feature for future development.

Member Impact on Expenses

When you add a new member to a group:

Existing Expenses
Future Expenses

New members are NOT retroactively added to existing expenses

Before adding Dave:
- Expense 1: Split between Alice, Bob, Charlie
- Expense 2: Split between Alice, Bob

After adding Dave:
- Expense 1: Still split between Alice, Bob, Charlie
- Expense 2: Still split between Alice, Bob
- Expense 3 (new): Can include Dave

New members start with a ₹0 balance and only participate in expenses added after they join.

New members can be included in any future expenseWhen adding an expense, the “Split Between” dropdown will include all current members:

// Source: AddExpense.jsx:159-163
{group.members.map((member) => (
  <MenuItem key={member.user._id} value={member.user._id}>
    {member.user.name}
  </MenuItem>
))}

By default, all members (including new ones) are selected for split.

Best Practices

Add Members Early

Add all expected members before recording expenses to avoid confusion about who should be included in splits.

Verify Email Addresses

Double-check email addresses before adding. Incorrect emails will result in “User not found” errors.

Communicate Changes

Let existing members know when you add someone new, especially if it affects how future expenses should be split.

Check Permissions

Remember that only group creators can add members. If you need to add someone and you’re not the creator, ask the creator to do it.

Troubleshooting

Error: 'User not found'

The email address you entered doesn’t match any registered BillBuddy user.Solutions:

Ask them to create a BillBuddy account first
Double-check the email for typos
Use a different email they may have registered with

Error: 'User is already a member'

The user you’re trying to add is already in the group.Check the member chips on the group page to see all current members.

Error: 'Not authorized to add members'

Only the group creator can add members. If you didn’t create the group, you cannot add new members.Contact the group creator and ask them to add the member.

Can't see 'Add Member' button

The “Add Member” button only appears if:

You are logged in
You are the group creator
You’re on the group detail page

If you’re not the creator, you won’t see this button.

Next Steps

Add Expenses

Start tracking shared expenses with your group members

View Balances

Learn how member balances are calculated and settled

API Reference

View the complete API documentation for member management

Get Started

Core Features

Guides

Configuration

Managing Group Members

Member Roles and Permissions

Group Creator

Group Members

Adding Members to a Group

Viewing Group Members

Understanding Member Chips

Member Data Structure

Adding Members During Group Creation

API Request Examples

Permission Checks

Removing Members

Member Impact on Expenses

Best Practices

Add Members Early

Verify Email Addresses

Communicate Changes

Check Permissions

Troubleshooting

Next Steps

Add Expenses

View Balances

API Reference

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Configuration

​Member Roles and Permissions

Group Creator

Group Members

​Adding Members to a Group

​Viewing Group Members

​Understanding Member Chips

​Member Data Structure

​Adding Members During Group Creation

​API Request Examples

​Permission Checks

​Removing Members

​Member Impact on Expenses

​Best Practices

Add Members Early

Verify Email Addresses

Communicate Changes

Check Permissions

​Troubleshooting

​Next Steps

Add Expenses

View Balances

API Reference

Build docs developers (and LLMs) love

Member Roles and Permissions

Adding Members to a Group

Viewing Group Members

Understanding Member Chips

Member Data Structure

Adding Members During Group Creation

API Request Examples

Permission Checks

Removing Members

Member Impact on Expenses

Best Practices

Troubleshooting

Next Steps