Skip to main content
All settlement endpoints require authentication. Include the JWT token in the Authorization header.

​
Create Settlement

Create a new settlement for a group. This calculates the minimum number of transactions needed to settle all debts and marks the group as settled.

​
Headers

​
Authorization
string
required
Bearer token for authentication

​
Request Body

​
group
string
required
Group ID to create settlement for

​
Response

​
message
string
Confirmation message
​
settlement
object
Settlement object containing transaction details

​
Example Request

cURL
curl -X POST https://api.billbuddy.com/api/settlements \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "group": "507f191e810c19729de860ea"
  }'

​
Example Response

200 OK
{
  "message": "Group settled successfully",
  "settlement": {
    "_id": "507f191e810c19729de860ed",
    "group": "507f191e810c19729de860ea",
    "type": "group",
    "status": "completed",
    "createdBy": "507f1f77bcf86cd799439011",
    "summary": [
      {
        "from": {
          "_id": "507f1f77bcf86cd799439012",
          "name": "Alice Smith"
        },
        "to": {
          "_id": "507f1f77bcf86cd799439011",
          "name": "John Doe"
        },
        "amount": 75.25
      },
      {
        "from": {
          "_id": "507f1f77bcf86cd799439013",
          "name": "Bob Johnson"
        },
        "to": {
          "_id": "507f1f77bcf86cd799439011",
          "name": "John Doe"
        },
        "amount": 50.00
      }
    ],
    "createdAt": "2024-01-15T16:00:00.000Z"
  }
}
The settlement algorithm calculates the minimum number of transactions needed to settle all debts in the group. This may result in fewer transactions than the actual number of expenses.

​
Error Responses

404 Not Found
{
  "message": "Group not found"
}
400 Bad Request
{
  "message": "This group has already been settled."
}
403 Forbidden
{
  "message": "Not authorized to settle this group"
}
500 Internal Server Error
{
  "message": "Server error"
}

​
Get Group Settlements

Retrieve all settlements for a specific group.

​
Headers

​
Authorization
string
required
Bearer token for authentication

​
Path Parameters

​
groupId
string
required
Group ID

​
Response

Returns an array of settlement objects with populated user information.

​
Example Request

cURL
curl -X GET https://api.billbuddy.com/api/settlements/group/507f191e810c19729de860ea \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Example Response

200 OK
[
  {
    "_id": "507f191e810c19729de860ed",
    "group": "507f191e810c19729de860ea",
    "type": "group",
    "status": "completed",
    "createdBy": {
      "_id": "507f1f77bcf86cd799439011",
      "name": "John Doe",
      "email": "[email protected]"
    },
    "summary": [
      {
        "from": {
          "_id": "507f1f77bcf86cd799439012",
          "name": "Alice Smith"
        },
        "to": {
          "_id": "507f1f77bcf86cd799439011",
          "name": "John Doe"
        },
        "amount": 75.25
      }
    ],
    "createdAt": "2024-01-15T16:00:00.000Z"
  }
]

​
Error Responses

404 Not Found
{
  "message": "Group not found"
}
403 Forbidden
{
  "message": "Not authorized"
}
500 Internal Server Error
{
  "message": "Server error"
}

​
Update Settlement Status

Update the status of a settlement. Only the person who created the settlement can update its status.

​
Headers

​
Authorization
string
required
Bearer token for authentication

​
Path Parameters

​
id
string
required
Settlement ID

​
Request Body

​
status
string
required
New settlement status. Options: pending, completed, cancelled

​
Response

Returns the updated settlement object.

​
Example Request

cURL
curl -X PUT https://api.billbuddy.com/api/settlements/507f191e810c19729de860ed/status \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed"
  }'

​
Example Response

200 OK
{
  "_id": "507f191e810c19729de860ed",
  "group": "507f191e810c19729de860ea",
  "type": "group",
  "status": "completed",
  "createdBy": "507f1f77bcf86cd799439011",
  "summary": [
    {
      "from": "507f1f77bcf86cd799439012",
      "to": "507f1f77bcf86cd799439011",
      "amount": 75.25
    }
  ],
  "createdAt": "2024-01-15T16:00:00.000Z"
}

​
Error Responses

404 Not Found
{
  "message": "Settlement not found"
}
403 Forbidden
{
  "message": "Not authorized"
}
500 Internal Server Error
{
  "message": "Server error"
}

​
Understanding Settlement Calculations

How the settlement algorithm works:
  1. Calculate Balances: For each member, calculate total amount paid minus total amount owed
  2. Identify Creditors and Debtors: Positive balances are creditors (owed money), negative balances are debtors (owe money)
  3. Minimize Transactions: Use a greedy algorithm to match the largest debtor with the largest creditor
  4. Generate Summary: Create a list of transactions that settles all debts with minimum transfers

​
Example Scenario

Imagine a group of 3 people with these expenses:
  • John paid $150 for groceries (split 3 ways)
  • Alice paid $90 for gas (split 3 ways)
  • Bob paid $60 for supplies (split 3 ways)
Balances:
  • John: +150−150 - 100 = +50(owed50 (owed 50)
  • Alice: +90−90 - 100 = -10(owes10 (owes 10)
  • Bob: +60−60 - 100 = -40(owes40 (owes 40)
Settlement transactions:
  • Bob pays John $40
  • Alice pays John $10
Result: All debts settled with just 2 transactions instead of potentially 6.

Build docs developers (and LLMs) love

Get started for freeTalk to us