All expense endpoints require authentication. Include the JWT token in the Authorization header.
Create Expense
Create a new expense and add it to a group.
Bearer token for authentication
Request Body
Expense description (max 100 characters)
Expense amount (must be non-negative)
Group ID where this expense belongs
Array of user IDs to split the expense among
Expense category. Options: Food, Travel, Shopping, Entertainment, Utilities, OtherDefault: Other
Response
Expense’s unique identifier
User ID of the person who paid
Example Request
curl -X POST https://api.billbuddy.com/api/expenses \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{
"description": "Groceries for camping",
"amount": 150.50,
"group": "507f191e810c19729de860ea",
"splitAmong": [
"507f1f77bcf86cd799439011",
"507f1f77bcf86cd799439012"
],
"category": "Food"
}'
Example Response
{
"_id": "507f191e810c19729de860eb",
"description": "Groceries for camping",
"amount": 150.50,
"paidBy": "507f1f77bcf86cd799439011",
"splitAmong": [
"507f1f77bcf86cd799439011",
"507f1f77bcf86cd799439012"
],
"group": "507f191e810c19729de860ea",
"category": "Food",
"date": "2024-01-15T14:30:00.000Z"
}
Error Responses
500 Internal Server Error
{
"message": "Server error"
}
Get Recent Expenses
Retrieve the 10 most recent expenses for the current user (either paid by them or split with them).
Bearer token for authentication
Response
Returns an array of expense objects sorted by date (newest first), limited to 10 items.
Example Request
curl -X GET https://api.billbuddy.com/api/expenses/recent \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Example Response
[
{
"_id": "507f191e810c19729de860eb",
"description": "Groceries for camping",
"amount": 150.50,
"paidBy": {
"_id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "[email protected]"
},
"splitAmong": [
{
"_id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "[email protected]"
},
{
"_id": "507f1f77bcf86cd799439012",
"name": "Alice Smith",
"email": "[email protected]"
}
],
"group": {
"_id": "507f191e810c19729de860ea",
"name": "Weekend Trip"
},
"category": "Food",
"date": "2024-01-15T14:30:00.000Z"
}
]
Get Group Expenses
Retrieve all expenses for a specific group.
Bearer token for authentication
Path Parameters
Response
Returns an array of expense objects for the specified group, sorted by date (newest first).
Example Request
curl -X GET https://api.billbuddy.com/api/expenses/group/507f191e810c19729de860ea \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Example Response
[
{
"_id": "507f191e810c19729de860eb",
"description": "Groceries for camping",
"amount": 150.50,
"paidBy": {
"_id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "[email protected]"
},
"splitAmong": [
{
"_id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "[email protected]"
},
{
"_id": "507f1f77bcf86cd799439012",
"name": "Alice Smith",
"email": "[email protected]"
}
],
"category": "Food",
"date": "2024-01-15T14:30:00.000Z"
},
{
"_id": "507f191e810c19729de860ec",
"description": "Gas for the trip",
"amount": 75.00,
"paidBy": {
"_id": "507f1f77bcf86cd799439012",
"name": "Alice Smith",
"email": "[email protected]"
},
"splitAmong": [
{
"_id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "[email protected]"
},
{
"_id": "507f1f77bcf86cd799439012",
"name": "Alice Smith",
"email": "[email protected]"
}
],
"category": "Travel",
"date": "2024-01-15T12:00:00.000Z"
}
]
Error Responses
{
"message": "Group not found"
}
{
"message": "Not authorized to access this group"
}
Get Single Expense
Retrieve details of a specific expense.
Bearer token for authentication
Path Parameters
Response
Returns an expense object with populated user information.
Example Request
curl -X GET https://api.billbuddy.com/api/expenses/507f191e810c19729de860eb \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Example Response
{
"_id": "507f191e810c19729de860eb",
"description": "Groceries for camping",
"amount": 150.50,
"paidBy": {
"_id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "[email protected]"
},
"splitAmong": [
{
"_id": "507f1f77bcf86cd799439011",
"name": "John Doe",
"email": "[email protected]"
},
{
"_id": "507f1f77bcf86cd799439012",
"name": "Alice Smith",
"email": "[email protected]"
}
],
"group": "507f191e810c19729de860ea",
"category": "Food",
"date": "2024-01-15T14:30:00.000Z"
}
Error Responses
{
"message": "Expense not found"
}
{
"message": "Not authorized to access this expense"
}
Update Expense
Update an existing expense. Only the person who paid can update the expense.
Bearer token for authentication
Path Parameters
Request Body
Updated expense description (max 100 characters)
Updated expense amount (must be non-negative)
Updated array of user IDs to split the expense among
Example Request
curl -X PUT https://api.billbuddy.com/api/expenses/507f191e810c19729de860eb \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{
"description": "Updated groceries description",
"amount": 165.75,
"category": "Food"
}'
Example Response
{
"_id": "507f191e810c19729de860eb",
"description": "Updated groceries description",
"amount": 165.75,
"paidBy": "507f1f77bcf86cd799439011",
"splitAmong": [
"507f1f77bcf86cd799439011",
"507f1f77bcf86cd799439012"
],
"group": "507f191e810c19729de860ea",
"category": "Food",
"date": "2024-01-15T14:30:00.000Z"
}
Error Responses
{
"message": "Expense not found"
}
{
"message": "Not authorized to update this expense"
}
Delete Expense
Delete an expense. Only the person who paid can delete the expense.
Bearer token for authentication
Path Parameters
Example Request
curl -X DELETE https://api.billbuddy.com/api/expenses/507f191e810c19729de860eb \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Example Response
{
"message": "Expense removed"
}
Error Responses
{
"message": "Expense not found"
}
{
"message": "Not authorized to delete this expense"
}
Settle Group Expenses
Calculate balances and settle all expenses in a group.
Bearer token for authentication
Path Parameters
Response
Object mapping user IDs to their final balance in the group
Example Request
curl -X POST https://api.billbuddy.com/api/expenses/settle/507f191e810c19729de860ea \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Example Response
{
"message": "Group settled successfully",
"balances": {
"507f1f77bcf86cd799439011": 75.25,
"507f1f77bcf86cd799439012": -75.25
}
}
Positive balance means the user is owed money. Negative balance means the user owes money.
Error Responses
{
"message": "Group not found"
}
{
"message": "Not authorized to settle this group"
}