Skip to main content
Groups are the foundation of BillBuddy, allowing you to track shared expenses with roommates, friends, or travel companions. This guide walks you through creating your first group.

​
Overview

When you create a group, you’ll need to:
  • Give it a name and optional description
  • Add members by their email addresses
  • Invite users who don’t have BillBuddy accounts yet
Once created, you and all members can add expenses, view balances, and settle up when ready.
1

Navigate to Create Group

From your dashboard, click the “Create Group” button or navigate to /create-group.You’ll see a clean form with fields for your group details.
2

Enter Group Details

Fill in the required information:
​
name
string
required
The name of your group (e.g., “Summer Road Trip”, “Apartment 4B”, “Office Lunch Club”)Must be 50 characters or less.
​
description
string
Optional description to help members understand the group’s purposeCan be up to 500 characters. Use this to add context like “Our monthly shared groceries” or “Weekend getaway to the mountains”.
// Source: CreateGroup.jsx:109-127
<TextField
  required
  fullWidth
  label="Group Name"
  name="name"
  value={formData.name}
  onChange={handleChange}
/>
<TextField
  fullWidth
  label="Description"
  name="description"
  multiline
  rows={4}
  value={formData.description}
  onChange={handleChange}
/>
3

Add Members

Add group members by entering their email addresses:
  1. Type an email address in the “Member Email” field
  2. Click the + button or press Enter to add them
  3. Repeat for all members you want to invite
Email addresses are validated in real-time. You’ll see an error if:
  • The email format is invalid
  • You try to add the same email twice
Members appear as chips below the input field. Click the X on any chip to remove that member.
// Source: CreateGroup.jsx:37-59
const handleAddMember = () => {
  if (!memberEmail) {
    setError('Please enter an email address');
    return;
  }

  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],
  });
  setMemberEmail('');
  setError('');
};
You must add at least one member to create a group. Groups with no members cannot be created.
4

Create the Group

Once you’ve added your group name and at least one member, click “Create Group”.The API will:
  1. Validate your input
  2. Create or find users for each email address
  3. Generate the new group
  4. Add all members with a starting balance of ₹0
// Backend: routes/groups.js:10-60
// Members are automatically created if they don't exist
const memberUsers = await Promise.all(
  members.map(async ({ email }) => {
    let user = await User.findOne({ email });
    if (!user) {
      user = new User({
        name: email.split('@')[0],
        email,
        password: Math.random().toString(36).slice(-8),
      });
      await user.save();
    }
    return user._id;
  })
);
Upon success, you’ll be redirected to the group page where you can start adding expenses.

​
What Happens Behind the Scenes

When you create a group, BillBuddy:
If you add a member who doesn’t have a BillBuddy account, the system automatically creates one using:
  • Their email address
  • A username derived from their email (everything before @)
  • A randomly generated temporary password
They’ll receive an invitation to set up their account properly.
Each member is added to the group with:
{
  user: userId,
  balance: 0  // Starting balance
}
You (the creator) are automatically included as the first member.

​
Example Group Creation

Here’s a complete example of creating a roommate expense group: 
{
  "name": "Apartment 4B - Monthly Expenses",
  "description": "Shared utilities, groceries, and household supplies",
  "members": [
    { "email": "[email protected]" },
    { "email": "[email protected]" },
    { "email": "[email protected]" }
  ]
}

​
Next Steps

Add Expenses

Learn how to add and split expenses among group members

Manage Members

Add or remove members from your group

Settle Debts

Understand how to settle up when it’s time to square accounts

API Reference

View the complete API documentation for group creation

​
Troubleshooting

Make sure you’ve filled in the group name field. Empty or whitespace-only names are not allowed.
You need to add at least one other person to create a group. Groups cannot exist with only the creator.
The email format is invalid. Ensure it follows the pattern: [email protected]
After creation, you should be automatically redirected to the group page. If not, check your Groups list from the dashboard. The group should appear there immediately.

Build docs developers (and LLMs) love

Get started for freeTalk to us