splitkaro: split expenses & settle up with UPI

A bill splitter for friends, flatmates and trips: track shared expenses, see who owes whom, and settle up with the fewest payments and one-tap UPI links.

Split karo is Hinglish for "split it". It is the phrase every group says at the end of a trip, right before the hisaab (the accounts) gets complicated.

Every trip, every shared flat and every office lunch ends with the same questions:

• Who paid for what, and who still owes whom?
• The hotel was ₹9,000, but a couple shared one room. How do we split that fairly?
• Five people owe each other money. Do we really need ten transfers?
• Somebody paid in dollars. What is that in rupees?

splitkaro answers all of them from your terminal. It keeps the group's records in one readable JSON file, does every calculation with exact decimal arithmetic so the totals always add up to the paisa, and works out the smallest set of payments that settles everyone, with UPI links you can open in GPay, PhonePe, Paytm or BHIM.

$ splitkaro balances
Asha             gets back ₹2,618.00
Ravi             owes ₹682.00
Meera            owes ₹1,936.00

$ splitkaro settle --upi
2 payment(s) settle everything:
  Meera pays Asha ₹1,936.00
    upi://pay?pa=asha%40okbank&pn=Asha&am=1936.00&cu=INR&tn=splitkaro%3A+Goa+trip
  Ravi pays Asha ₹682.00
    upi://pay?pa=asha%40okbank&pn=Asha&am=682.00&cu=INR&tn=splitkaro%3A+Goa+trip

Contents

• Features
• Install
• A full example: a Goa trip
• Ways to split
• Command reference
• Your data
• Using splitkaro from Python
• How it works
• Roadmap
• Contributing
• License

Features

Install

pip install splitkaro

Or straight from GitHub:

pip install git+https://github.com/K70281095/splitkaro.git

Check it works:

splitkaro --version

A full example: a Goa trip

Asha, Ravi and Meera go to Goa. Asha travels with her partner, so on the hotel she counts as two.

splitkaro init "Goa trip"
splitkaro member add Asha Ravi Meera
splitkaro member upi Asha asha@okbank          # so others can pay her with one tap

# Hotel: Asha paid, split by shares (Asha 2, Ravi 1, Meera 1)
splitkaro add "Hotel (2 nights)" 9000 --paid-by Asha --shares Asha=2,Ravi=1,Meera=1 --category stay

# Dinner: Ravi paid, split equally among everyone (the default)
splitkaro add "Dinner at the shack" 2400 --paid-by Ravi --category food

# Scooters: two people paid, and only they used them
splitkaro add "Scooter rental" 1500 --paid-by Asha=1000 --paid-by Meera=500 --among Asha,Meera --category travel

# Parasailing was paid in dollars
splitkaro rate USD 83.20
splitkaro add "Parasailing" 30 --currency USD --paid-by Meera --category fun

# Groceries: everyone took different things
splitkaro add "Groceries" 1260 --paid-by Ravi --exact Asha=500,Ravi=460,Meera=300 --category food

Where does everyone stand, and how do they square up?

$ splitkaro settle
2 payment(s) settle everything:
  Meera pays Asha ₹1,936.00
  Ravi pays Asha ₹682.00

Where did the money go?

$ splitkaro report
Goa trip: 5 expense(s), ₹16,656.00 in total

By category
  stay                  ₹9,000.00  54%
  food                  ₹3,660.00  22%
  fun                   ₹2,496.00  15%
  travel                ₹1,500.00  9%

By month
  2026-11              ₹16,656.00

  member                     paid          share
  Asha                 ₹10,000.00      ₹7,382.00
  Ravi                  ₹3,660.00      ₹4,342.00
  Meera                 ₹2,996.00      ₹4,932.00

Meera wants to see exactly how she ended up owing ₹1,936:

$ splitkaro statement meera
2026-11-01      -₹2,250.00      -₹2,250.00  #1 Hotel (2 nights)
2026-11-01        -₹800.00      -₹3,050.00  #2 Dinner at the shack
2026-11-02        -₹250.00      -₹3,300.00  #3 Scooter rental
2026-11-02       ₹1,664.00      -₹1,636.00  #4 Parasailing
2026-11-03        -₹300.00      -₹1,936.00  #5 Groceries

Meera owes ₹1,936.00

Once the money has moved, record it, and everyone is back to zero:

splitkaro pay Meera Asha 1936
splitkaro pay Ravi Asha 682
splitkaro settle      # Everyone is settled up. 🎉

The same trip is available as examples/goa-trip.csv, which you can load with splitkaro import examples/goa-trip.csv.

Ways to split

Whoever paid is given with --paid-by NAME, or --paid-by NAME=AMOUNT repeated when several people paid the same bill. Names are case-insensitive.

Command reference

Every command accepts --file PATH (or the SPLITKARO_FILE environment variable) to work with more than one group, for example splitkaro -f flat.json balances.

Errors are printed as splitkaro: <message> with exit code 1, and nothing is saved when a command fails.

Your data

A group lives in a single JSON file, splitkaro.json by default (shortened here):

{
  "version": 1,
  "name": "Goa trip",
  "currency": "INR",
  "members": [{ "name": "Asha", "upi": "asha@okbank" }, { "name": "Ravi", "upi": null }],
  "expenses": [
    {
      "id": 2,
      "date": "2026-11-01",
      "description": "Dinner at the shack",
      "amount": "2400.00",
      "paid_by": { "Ravi": "2400.00" },
      "split": { "kind": "equal", "among": ["Asha", "Ravi", "Meera"], "values": {} }
    }
  ]
}

• Amounts are stored as strings, never floats, so nothing is ever rounded away.
• Files are written atomically: a crash or a full disk cannot leave a half-written file.
• There is no account, server or tracking. Share the file however your group likes.

The CSV format is documented in docs/csv-format.md.

Using splitkaro from Python

import datetime as dt
from decimal import Decimal

from splitkaro import Expense, Group, Split, balances, settle

group = Group("Flat 302")
for name in ("Asha", "Ravi", "Meera"):
    group.add_member(name)

group.add_expense(Expense(
    id=0, description="Electricity", amount=Decimal("3120"),
    paid_by={"Ravi": Decimal("3120")}, split=Split.equal(["Asha", "Ravi", "Meera"]),
    date=dt.date(2026, 11, 5), currency="INR", category="bills",
))

for t in settle(balances(group)):
    print(f"{t.sender} pays {t.receiver} {t.amount}")

How it works

• Rounding: amounts are split with the largest-remainder method on whole paise, so the parts always add up to the exact total and nobody is ever short-changed by more than one paisa.
• Balances: each member's balance is what they paid minus their share, plus payments made minus payments received. Balances always add up to exactly zero.
• Settling: exact matches (someone owes exactly what someone else is owed) are paired first; the rest is settled greedily between the largest debtor and the largest creditor. This never needs more than n − 1 payments.

The details, with worked examples, are in docs/how-it-works.md.

Roadmap

• Recurring expenses (rent, Wi-Fi, maid) added automatically each month
• UPI QR codes in the terminal
• Simplify across groups (one payment per pair of people for several trips)
• Budgets per category with warnings
• Hindi and other Indian language output
• A small web or mobile front end on top of the same file format

Ideas and pull requests are welcome, see the issues.

Contributing

Bug reports, ideas, translations and code are all welcome. Please read CONTRIBUTING.md and the Code of Conduct. To report a security problem, see SECURITY.md.

License

MIT © 2026 Kanhaiya Kumar

UPI is a system of the National Payments Corporation of India. splitkaro only creates standard upi://pay links and never handles money, bank details or PINs.