Concepts
The rules the API holds you to, and why. Most of them exist because money that is almost right is wrong.
Money is an integer in minor units#
Every amount is an integer in the currency's minor unit plus an ISO 4217 currency code. Never a float, never a decimal string (the one exception is the MCP tools, which take "12.50" because that is how people talk).
amount_minor: 120000 with currency: "INR" is ₹1,200.00, because a rupee has 100 paise. How many minor units make a major one depends on the currency's exponent:
| Code | Currency | Exponent | Amount | amount_minor |
|---|---|---|---|---|
INR | Indian rupee | 2 | ₹1,200.00 | 120000 |
USD | US dollar | 2 | $12.50 | 1250 |
EUR | Euro | 2 | €9.99 | 999 |
GBP | Pound sterling | 2 | £40.00 | 4000 |
JPY | Japanese yen | 0 | ¥1,250 | 1250 |
KRW | South Korean won | 0 | ₩15,000 | 15000 |
KWD | Kuwaiti dinar | 3 | KD 12.500 | 12500 |
BHD | Bahraini dinar | 3 | BD 3.750 | 3750 |
No minor unit (exponent 0): BIF CLP DJF GNF ISK JPY KMF KRW PYG RWF UGX VND VUV XAF XOF XPF. Three decimals (exponent 3): BHD IQD JOD KWD LYD OMR TND. Every other ISO 4217 code: 2. This list is read from the server's own table when this site is built.
So "12.50" is 1250 in USD, 12500 in KWD, and not a valid yen amount at all: ¥1,250 is 1250. Getting the exponent wrong is not a rounding error, it is a bill a hundred times too big.
Convert with text or integer arithmetic, never floating point. These helpers use the same exponent table as the server:
const EXPONENT = {
BIF: 0, CLP: 0, DJF: 0, GNF: 0, ISK: 0, JPY: 0, KMF: 0, KRW: 0,
PYG: 0, RWF: 0, UGX: 0, VND: 0, VUV: 0, XAF: 0, XOF: 0, XPF: 0,
BHD: 3, IQD: 3, JOD: 3, KWD: 3, LYD: 3, OMR: 3, TND: 3,
};
const exponent = (currency) => EXPONENT[currency.toUpperCase()] ?? 2;
// "12.50" -> 1250 (USD). Refuses more decimals than the currency has.
function toMinor(amount, currency) {
const m = /^(\d+)(?:\.(\d+))?$/.exec(String(amount).trim());
if (!m) throw new Error(`not a positive decimal: ${amount}`);
const exp = exponent(currency);
const frac = m[2] || "";
if (frac.length > exp) throw new Error(`${currency} has ${exp} decimal places`);
return Number(m[1] + frac.padEnd(exp, "0"));
}
// 1250 (USD) -> "12.50"; -500 (JPY) -> "-500"
function fromMinor(minor, currency) {
const exp = exponent(currency);
const digits = String(Math.abs(minor)).padStart(exp + 1, "0");
const major = exp ? `${digits.slice(0, -exp)}.${digits.slice(-exp)}` : digits;
return (minor < 0 ? "-" : "") + major;
}from decimal import Decimal
EXPONENT = {
"BIF": 0, "CLP": 0, "DJF": 0, "GNF": 0, "ISK": 0, "JPY": 0, "KMF": 0, "KRW": 0,
"PYG": 0, "RWF": 0, "UGX": 0, "VND": 0, "VUV": 0, "XAF": 0, "XOF": 0, "XPF": 0,
"BHD": 3, "IQD": 3, "JOD": 3, "KWD": 3, "LYD": 3, "OMR": 3, "TND": 3,
}
def exponent(currency: str) -> int:
return EXPONENT.get(currency.upper(), 2)
def to_minor(amount: str, currency: str) -> int:
""""12.50" -> 1250 (USD). Refuses more decimals than the currency has."""
d = Decimal(str(amount).strip())
exp = exponent(currency)
if d <= 0:
raise ValueError(f"{amount!r} must be more than zero")
if -d.as_tuple().exponent > exp:
raise ValueError(f"{currency} has {exp} decimal places")
return int(d.scaleb(exp))
def from_minor(minor: int, currency: str) -> Decimal:
"""1250 (USD) -> Decimal('12.50')"""
return Decimal(minor).scaleb(-exponent(currency))To show an amount, format the major value with the currency, for example new Intl.NumberFormat("en-IN", { style: "currency", currency: "INR" }).format(fromMinor(120000, "INR")) gives "₹1,200.00".
Currencies are never added together#
A group has a default currency, but any bill can be in any currency, and balances are kept per currency. A member can be owed ₹2,000 and owe ¥3,000 in the same group at the same time; those are two balances, not one. Every balance, position and insight is a list of {currency, …} entries for this reason.
A bill stays in the currency it was added in. Leave out convert_to and a ¥3,000 bill in a rupee group is kept in yen: it never "needs a rate", and its balances are in yen. Send "convert_to": "INR" (or an fx_rate, which is always into the group's currency) to convert it for the group's totals. Either way the money is posted in the bill's own currency; a conversion is only how it is read. Bills in another currency also carry display_rate, the published market rate for their day, for showing "about ₹1,650" beside them; it never changes a balance.
Never sum across currencies in your own code either. If you need one figure, convert with a rate you and your group agree on. A bill in another currency can carry the group's agreed rate (PUT /v1/groups/{groupID}/expenses/{expenseID}/fx-rate, group currency per unit, as a decimal string such as "0.5624"); GET /v1/fx/quote gives a published market rate for reference.
Members, accounts and kept places#
A person appears in a group as a member, with a member id that is local to that group. Bills, splits and payments always name people by member id: the same person has a different member id in each group they are in.
my_member_idonGET /v1/groups/{groupID}is your own member id in that group.user_idon a member is the account behind it, when there is one. Use it to recognise the same person across groups.- A member with
is_ghost: trueis a kept place: somebody without an account (yet), so bills can include them. Add one withPOST /v1/groups/{groupID}/members. When they join, they take over the place with its history and balance intact.
Balances and their sign#
A member's balance is their position against the group, per currency:
- Positive: the group owes them. They paid more than their share.
- Negative: they owe the group.
- A group's balances in one currency always add up to zero.
your_position on GET /v1/groups is your own balance in each group. GET /v1/me/balances returns every group you are in with all its members' balances; group by user_id to see a person across groups, and keep each currency separate. In a two-person group, the other person's negative balance is exactly what they owe you.
Read-only example groups (see below) are left out of /v1/me/balances: their money is an example.
Idempotency: every write carries your id#
Every write takes a UUID that you generate, in id (or revision_id for an edit or delete). It is the write's idempotency key:
| You send | You get |
|---|---|
| A new id | The write happens: 201 (or 200 for an edit). |
| The same id with the same content | A replay: 200 with the same result. Nothing is written twice. |
| The same id with different content | 409 idempotency_conflict. |
This is what makes retrying safe. If a request times out, send the exact same request again: either the first one landed and you get it back, or it did not and now it does. Generate the id once per action, before the first attempt, and reuse it on every retry.
Any UUID is accepted. UUIDv7 is recommended: it starts with the time, so ids sort by when they were made. The Quickstart has a UUIDv7 helper for JavaScript and Python; uuidgen gives a v4, which works too.
Editing a bill restates the whole bill#
PATCH /v1/groups/{groupID}/expenses/{expenseID} does not merge. You send the whole bill as it should be now, including split_type and participants, plus:
revision_id: a new UUID for this edit (the idempotency key).base_version: theversionyou read.
Why restate: a partial update that only fixed a typo in the description would otherwise fall back to "split equally among everyone", pulling in somebody who joined later or flattening a 70/30 rent split to 50/50. Why the version: if somebody else changed the bill after you read it, your edit is refused with 409 stale_version rather than quietly overwriting theirs. Read the bill again, reapply your change, and send it with the new version.
The safe pattern is read, change, send:
const url = `${API}/v1/groups/${groupId}/expenses/${expenseId}`;
const bill = await fetch(url, { headers }).then((r) => r.json());
if (!bill.can_edit) throw new Error("not yours to edit in this group");
const res = await fetch(url, {
method: "PATCH",
headers: { ...headers, "Content-Type": "application/json" },
body: JSON.stringify({
revision_id: uuidv7(),
base_version: bill.version,
description: "Dinner at Thalassa (with dessert)",
amount_minor: 135000,
currency: bill.currency,
occurred_on: bill.occurred_on,
split_type: bill.split_type,
participants: bill.splits.map((s) => s.member_id),
}),
});
if (res.status === 409) console.log((await res.json()).error.code); // stale_version: read againurl = f"{API}/v1/groups/{group_id}/expenses/{expense_id}"
bill = session.get(url).json()
if not bill["can_edit"]:
raise SystemExit("not yours to edit in this group")
r = session.patch(url, json={
"revision_id": uuid7(),
"base_version": bill["version"],
"description": "Dinner at Thalassa (with dessert)",
"amount_minor": 135000,
"currency": bill["currency"],
"occurred_on": bill["occurred_on"],
"split_type": bill["split_type"],
"participants": [s["member_id"] for s in bill["splits"]],
})
if r.status_code == 409:
print(r.json()["error"]["code"]) # stale_version: read againThis example keeps an equal split among the same people. Leaving out payers keeps the bill's own payer, never the person editing; a bill with several payers must restate them, adding up to the new amount_minor. An EXACT, PERCENT or SHARES bill must also restate its shares, percents or weights.
Deleting is DELETE /v1/groups/{groupID}/expenses/{expenseID} with revision_id and base_version. The ledger is append-only: a delete is a tombstone that reverses the bill's effect on balances, and the bill stays in lists with deleted: true and in its history.
Pagination#
Lists that grow page with a cursor. Read next_cursor from a page and pass it back as ?cursor= for the next; when there is no next_cursor, you have the last page. Cursors are opaque: do not build or edit them.
async function allBills(groupId) {
const out = [];
let cursor = "";
do {
const qs = new URLSearchParams({ limit: "100", ...(cursor && { cursor }) });
const page = await fetch(`${API}/v1/groups/${groupId}/expenses?${qs}`, { headers }).then((r) => r.json());
out.push(...page.expenses);
cursor = page.next_cursor || "";
} while (cursor);
return out;
}def all_bills(group_id: str) -> list[dict]:
out, cursor = [], None
while True:
params = {"limit": 100, **({"cursor": cursor} if cursor else {})}
page = session.get(f"{API}/v1/groups/{group_id}/expenses", params=params).json()
out += page["expenses"]
cursor = page.get("next_cursor")
if not cursor:
return outThe activity feeds are different: they are a delta from a sequence number. Pass the next_since of your last read as ?since=, and keep reading while more is true.
Read-only groups and bills#
A group can be read-only, for example the example groups a new account starts with. Every write under it answers 403 read_only. A single bill can also be read-only (read_only: true on the bill): it cannot be edited, deleted or given a rate, though it can still be commented on. Check read_only on the group or the bill before offering a write.
Who may edit a bill#
The author of a bill can always change it. Changing other people's bills is a group policy, read with GET /v1/groups/{groupID}/editors:
OWNER(the default): the group's owner, plus any members the owner names inmember_ids.EVERYONE: every member.
Anybody else gets 403 not_editor. You do not have to work this out yourself: GET /v1/groups/{groupID}/expenses/{expenseID} returns can_edit for you.
Captures and suggestions: nothing auto-posts#
POST /v1/captures takes a line of text ("dinner 1200 with Ravi and Priya, I paid") and returns a suggestion: a draft bill with the amount, description, payer and people filled in as far as the text says. A suggestion moves no money. It becomes a bill only when somebody confirms it with POST /v1/suggestions/{suggestionID}/confirm, optionally correcting the amount, description or people on the way; or it is dismissed with POST /v1/suggestions/{suggestionID}/dismiss.
- Pending suggestions are listed by
GET /v1/suggestionsand appear in the app's inbox, so a capture from a script can be confirmed on a phone. - Confirming is idempotent: the bill's id is derived from the suggestion's, so a double tap posts one bill.
- A suggestion that is no longer pending answers
409 not_pending; one without a name or an amount answers400 incomplete_draftuntil you supply it on confirm. - Reading the text needs the parser. On a server without one, the capture still becomes a suggestion, but only with the defaults: the line as its name, you as payer and only participant, and the amount left for you to fill in when you confirm.
Payments are assertions#
Dimesum never holds or moves money. POST /v1/groups/{groupID}/settlements records that you paid somebody, in your own bank, payment app or cash:
from_member_idmust be your own member id;to_member_idis who you paid.- The amount is any positive figure: part of what you owe, all of it, or more. Paying more than you owe, or paying when you owe nothing, leaves them owing you the difference.
methodandreference(the UPI reference, the bank's transaction id) help the other person find it.
The person paid then confirms (POST /v1/groups/{groupID}/settlements/{settlementID}/confirm) or disputes it (POST /v1/groups/{groupID}/settlements/{settlementID}/dispute, which reverses it). If they do neither, it confirms itself after 48 hours. A payment moves through RECORDED, POSTED and CONFIRMED, or ends REVERSED. The payer cannot confirm their own payment (403 self_confirm).
Repeats#
A repeat is a standing instruction, such as rent on the 1st or a subscription every month. POST /v1/groups/{groupID}/recurring creates one with freq (DAILY, WEEKLY or MONTHLY), day_of_month (1 to 28) or weekday (0 is Sunday), and the bill's content. Each period it posts an ordinary bill, with an id derived from the repeat and the period, so a period can never post twice. Leave out participants and each bill is split among whoever is in the group on the day it posts. Pause, resume and edit repeats in the app.
Dates and time zones#
occurred_on is a calendar date (YYYY-MM-DD), not a timestamp. Left out, it is today in the group's pinned time zone if it has one, otherwise in yours (timezone on GET /v1/me). Timestamps such as created_at are RFC 3339 in UTC.
Report objects#
A few responses are reports whose shape grows as the app grows, so the reference lists them as open objects. Ignore fields you do not know. The ones worth knowing:
- Activity (
GET /v1/me/activity,GET /v1/groups/{groupID}/activity):items(each withseq,kindsuch asEXPENSE_AMENDED,SETTLEMENT_RECORDEDorMEMBER_ADDED,occurred_at,subject_id,actor_member_id, andamount_minorwithcurrencywhere money is involved; the account-wide feed addsgroup_id),next_sinceandmore. - Insights (
GET /v1/me/insights,GET /v1/groups/{groupID}/insights):period, and figures such asmy_share,totals,months,daysandby_group. Every figure is{sums, folded, missing}:sumsper currency,foldedconverted at the group's agreed rates, andmissingnaming currencies that had no rate to fold with. - Repeats (
GET /v1/groups/{groupID}/recurring): each rule'sid,status,description,amount_minor,currency,freq,day_of_month,weekdayandnext_on. - Write-offs (
GET /v1/groups/{groupID}/write-offs): debts a creditor forgave, made in the app.