expensesplit

A Python library for splitting shared expenses between a group of people. Inspired by Splitwise. Uses the Minimize Cash Flow algorithm to produce the fewest possible settlement transactions.

Install

pip install expensesplit

Quick Start

from expensesplit import calculate_balances, calculate_settlements

members = ['Arya', 'John', 'Sara']

expenses = [
    {'payer': 'Arya', 'amount': 90.0},   # Arya paid $90 for dinner
    {'payer': 'John', 'amount': 30.0},   # John paid $30 for taxi
]

# Step 1 — calculate each person's net balance
balances = calculate_balances(members, expenses)
# {'Arya': 50.0, 'John': -10.0, 'Sara': -40.0}
# Arya is owed $50, John owes $10, Sara owes $40

# Step 2 — calculate minimum payments to settle everything
settlements = calculate_settlements(balances)
# [{'from': 'Sara', 'to': 'Arya', 'amount': 40.0},
#  {'from': 'John', 'to': 'Arya', 'amount': 10.0}]

for s in settlements:
    print(f"{s['from']} pays {s['to']}  ${s['amount']:.2f}")

Split Modes

Equal Split (default)

from expensesplit import split_amount

shares = split_amount(90.0, ['Arya', 'John', 'Sara'])
# {'Arya': 30.0, 'John': 30.0, 'Sara': 30.0}

Custom Amounts

shares = split_amount(
    100.0,
    ['Arya', 'John', 'Sara'],
    split_type='custom',
    values={'Arya': 50.0, 'John': 30.0, 'Sara': 20.0}
)
# {'Arya': 50.0, 'John': 30.0, 'Sara': 20.0}

Percentage Split

shares = split_amount(
    200.0,
    ['Arya', 'John', 'Sara'],
    split_type='percentage',
    values={'Arya': 50, 'John': 30, 'Sara': 20}
)
# {'Arya': 100.0, 'John': 60.0, 'Sara': 40.0}

Custom Shares on Expenses

expenses = [
    {
        'payer': 'Arya',
        'amount': 100.0,
        'shares': {'Arya': 50.0, 'John': 30.0, 'Sara': 20.0}  # custom split
    },
    {
        'payer': 'John',
        'amount': 60.0
        # no 'shares' key = equal split
    },
]

balances = calculate_balances(['Arya', 'John', 'Sara'], expenses)

Settlement Status

from expensesplit import get_settlement_status

get_settlement_status(total_owed=100.0, amount_paid=100.0)  # 'settled'
get_settlement_status(total_owed=100.0, amount_paid=40.0)   # 'partial'
get_settlement_status(total_owed=100.0, amount_paid=0.0)    # 'pending'

How the Algorithm Works

The library uses the Minimize Cash Flow algorithm:

1. Calculate each member's net balance (paid minus owed)
2. Separate into creditors (positive balance) and debtors (negative balance)
3. Greedily match the largest debtor with the largest creditor
4. Repeat until all balances are zero

This guarantees the fewest possible transactions to settle all debts.

License

MIT