Lightsplit

Get the shortest set of payments that clears every balance in the group — the answer to 'who owes whom, and how do we settle up?'. Each suggested payment names both members, so you can read it out directly. When the user then actually pays one of them, record it with create_transfer. An empty list means everybody is already square. The group to act on. Accepts either a Lightsplit group id or any Lightsplit share link (web, LINE or Telegram) — pass through whatever the user gave you, unchanged.

get_settle_transfers

Break a group's spending down by category: per-category sums of money spent (expense) and money received (income), in the group's primary currency. Returns two lists, expense and income. Each row is {category, amount_for_primary}, where amount_for_primary carries the ledger's sign — expense rows are NEGATIVE (money out), income rows positive (money in) — so a row's magnitude is what the group spent or received on that category. A row with an empty category is spending Lightsplit has not categorised. Optionally narrow it: `member_id` reports just that one member's share of each transaction, and `from`/`to` restrict it to a date window. The group to act on. Accepts either a Lightsplit group id or any Lightsplit share link (web, LINE or Telegram) — pass through whatever the user gave you, unchanged.

get_spending_breakdown

List the caller's Lightsplit groups — at most 20, in the order the Lightsplit app shows them: pinned groups first, then the newest. Use this when the user names a group ('add this to the Tokyo trip') instead of giving you a share link or id: find it here and pass its group.id as the other tools' `group` argument. If more than one group could be the one they mean, ask rather than guess. When has_more is true the caller belongs to older groups that are not listed. If the group they mean is not here, ask them for its share link instead of saying it does not exist.

list_latest_groups

List a group's shared reminders — its running to-buy / to-do list, the same list everyone in the group sees. Each reminder carries: id (what you pass to complete_reminder, update_reminder and delete_reminder), what (the reminder text), completed (whether it has been ticked off), and an optional currency+amount when the reminder has a price attached. The group to act on. Accepts either a Lightsplit group id or any Lightsplit share link (web, LINE or Telegram) — pass through whatever the user gave you, unchanged.

list_reminders

List a group's transactions, newest first. Each transaction carries its from/to legs already resolved to display names, so one call is enough to tell the user '1200 for dinner, paid by Ming'. This is where transaction ids come from: call it before update_transaction or delete_transaction. Paging: pass the previous page's `next_cursor` back verbatim as `cursor`, and stop when next_cursor comes back null. The cursor is opaque — never construct or edit one. Narrow with `from`/`to` when the user names a day or a period. The group to act on. Accepts either a Lightsplit group id or any Lightsplit share link (web, LINE or Telegram) — pass through whatever the user gave you, unchanged.

list_transactions

Record an expense: money the group spent, to be shared out among its members. Member ids come from get_group; call it first if you do not already have this group's roster. In that roster is_caller marks the member row belonging to the person whose token this is, which is who 'I', 'me' and 'my share' refer to. HOW THE MONEY IS DIVIDED `splits` says who the money was FOR: - omit `splits` entirely -> split equally among ALL active members of the group - [{member_id}, {member_id}] -> split equally among just those people - [{member_id, share: 2}, {member_id, share: 1}] -> weighted, so the first person carries a double portion - [{member_id, amount: 300}, {member_id, amount: 900}] -> exact figures; then EVERY entry needs an amount and they must add up to `amount` Mixing `share` and `amount` in one call is rejected rather than guessed at. `payers` says who PUT THE MONEY IN: - omit `payers` -> the caller (the member with is_caller=true) paid all of it - [{member_id}] -> that one member paid all of it - [{member_id, amount}, ...] -> several payers; every one needs an amount and they must add up to `amount` Every figure is POSITIVE. The direction of the money comes from which tool you call, never from a minus sign. ATTACHING A RECEIPT is not supported right now — there is no way to get an image from this conversation into Lightsplit through these tools, so do not offer it or claim it worked. `image_cache_keys` takes handles, never pixels, and a photo here cannot be turned into one; leave it out. What to do instead: record the transaction, then give the user the reply's `links` and tell them they can add the photo on that page themselves. The category icon is likewise not settable here: Lightsplit infers it from `what`. WHEN YOU REPORT THE RESULT, give the user the reply's `links` — every non-null one, labelled by channel — so they can open the transaction and check it. Display links on one compact line as Markdown text links, with the exact labels and order: [LINE](<links.line>) · [Telegram](<links.telegram>) · [Web](<links.web>). Replace each placeholder with the exact URL from that reply's `links` object; preserve the entire URL, including all query parameters. Omit null channels and their separators. Render the links normally, not inside a code span or code block. Only show raw URLs if the user explicitly asks for them.

create_expense

Record an income: money the group RECEIVED and shares out — a refund, a deposit returned, a shared payout. Use create_expense for money spent. Member ids come from get_group; call it first if you do not already have this group's roster. In that roster is_caller marks the member row belonging to the person whose token this is, which is who 'I', 'me' and 'my share' refer to. HOW THE MONEY IS DIVIDED `splits` says who the money was FOR: - omit `splits` entirely -> split equally among ALL active members of the group - [{member_id}, {member_id}] -> split equally among just those people - [{member_id, share: 2}, {member_id, share: 1}] -> weighted, so the first person carries a double portion - [{member_id, amount: 300}, {member_id, amount: 900}] -> exact figures; then EVERY entry needs an amount and they must add up to `amount` Mixing `share` and `amount` in one call is rejected rather than guessed at. `payers` says who PUT THE MONEY IN: - omit `payers` -> the caller (the member with is_caller=true) paid all of it - [{member_id}] -> that one member paid all of it - [{member_id, amount}, ...] -> several payers; every one needs an amount and they must add up to `amount` Every figure is POSITIVE. The direction of the money comes from which tool you call, never from a minus sign. ATTACHING A RECEIPT is not supported right now — there is no way to get an image from this conversation into Lightsplit through these tools, so do not offer it or claim it worked. `image_cache_keys` takes handles, never pixels, and a photo here cannot be turned into one; leave it out. What to do instead: record the transaction, then give the user the reply's `links` and tell them they can add the photo on that page themselves. The category icon is likewise not settable here: Lightsplit infers it from `what`. WHEN YOU REPORT THE RESULT, give the user the reply's `links` — every non-null one, labelled by channel — so they can open the transaction and check it. Display links on one compact line as Markdown text links, with the exact labels and order: [LINE](<links.line>) · [Telegram](<links.telegram>) · [Web](<links.web>). Replace each placeholder with the exact URL from that reply's `links` object; preserve the entire URL, including all query parameters. Omit null channels and their separators. Render the links normally, not inside a code span or code block. Only show raw URLs if the user explicitly asks for them.

create_income

Record a transfer: one member handing money directly to another, usually to settle up. Nothing is shared out — this is not a group cost, so there is no `splits` argument. Use this after the user actually pays somebody, typically one of the payments get_settle_transfers suggested. `payer_member_id` defaults to the caller (is_caller=true), so 'I paid Hua 800' needs only the receiver and the amount. Member ids come from get_group; call it first if you do not already have this group's roster. In that roster is_caller marks the member row belonging to the person whose token this is, which is who 'I', 'me' and 'my share' refer to. IF THIS PAYMENT IS ONE get_settle_transfers SUGGESTED, pass `is_settle_up: true` with the suggestion's own payer, receiver and amount. Lightsplit re-checks the plan and refuses with settle_up_state_changed if the balances have moved since you read it — someone else recorded something — which is a refusal to act on rather than to work around: call get_settle_transfers again, tell the user what the plan says now, and record what they actually paid. Leave the flag out when the payment is not one of the suggestions, including a partial or rounded-off one. ATTACHING A RECEIPT is not supported right now — there is no way to get an image from this conversation into Lightsplit through these tools, so do not offer it or claim it worked. `image_cache_keys` takes handles, never pixels, and a photo here cannot be turned into one; leave it out. What to do instead: record the transaction, then give the user the reply's `links` and tell them they can add the photo on that page themselves. That applies here too, and a settle-up is where it bites most: a bank-app screenshot is the commonest receipt there is, so expect the user to have one, and send them to the transaction's page with it rather than saying you attached it. WHEN YOU REPORT THE RESULT, give the user the reply's `links` — every non-null one, labelled by channel — so they can open the transaction and check it. Display links on one compact line as Markdown text links, with the exact labels and order: [LINE](<links.line>) · [Telegram](<links.telegram>) · [Web](<links.web>). Replace each placeholder with the exact URL from that reply's `links` object; preserve the entire URL, including all query parameters. Omit null channels and their separators. Render the links normally, not inside a code span or code block. Only show raw URLs if the user explicitly asks for them.

create_transfer

Remove an unseated placeholder member (is_seated=false) from a group. Three refusals worth knowing before you call: - Only the group's OWNER may remove anyone. Anybody else is refused before either of the checks below is reached, so a non-owner gets this answer whatever the member looks like. - A SEATED member — a real Lightsplit account holder, including the caller themselves — cannot be removed here. They have to leave the group themselves in the Lightsplit app; say so rather than trying again. - A member with a non-zero balance cannot be removed. Settle them up first (see get_settle_transfers and create_transfer), then remove them. Member ids come from get_group; call it first if you do not already have this group's roster. In that roster is_caller marks the member row belonging to the person whose token this is, which is who 'I', 'me' and 'my share' refer to.

remove_member

Reopen a reminder that was ticked off, putting it back on the group's active list. Get the reminder_id from list_reminders.

uncomplete_reminder

Turn a Lightsplit share link into a group id, and return the same group's links for the other channels. You rarely need this: every other tool's `group` argument already accepts a share link. Reach for it when the user has a link and wants the same group on other channels ('send me the LINE version') — and hand back every link that comes with it, not just the one they named, so they can still choose. Display links on one compact line as Markdown text links, with the exact labels and order: [LINE](<links.line>) · [Telegram](<links.telegram>) · [Web](<links.web>). Replace each placeholder with the exact URL from that reply's `links` object; preserve the entire URL, including all query parameters. Omit null channels and their separators. Render the links normally, not inside a code span or code block. Only show raw URLs if the user explicitly asks for them. It only succeeds for a group the caller may already see, so it cannot be used to probe whether a link is real.

resolve_group_link

Set (or clear) the group's shared spending budget — the cap everyone in the group sees. Only the group's OWNER may set it; anyone else is refused. To set one, pass `amount` (>= 0, in the group's primary currency) and `period_type` ('monthly' or 'all_time'). To CLEAR it, omit both `amount` and `period_type`. The group to act on. Accepts either a Lightsplit group id or any Lightsplit share link (web, LINE or Telegram) — pass through whatever the user gave you, unchanged.

set_group_budget

Set (or clear) the caller's OWN personal spending budget in a group — private to them, not the shared group budget. The caller must be a member of the group. To set one, pass `amount` (>= 0, in the group's primary currency) and `period_type` ('monthly' or 'all_time'). To CLEAR it, omit both. The group to act on. Accepts either a Lightsplit group id or any Lightsplit share link (web, LINE or Telegram) — pass through whatever the user gave you, unchanged.

set_personal_budget

Rename a group, change its note, or change who may open its share links. Only the fields you pass are changed; everything else is left alone. This is where you open a group up for sharing: other people can only get in through a share link, and only `public_permission` 'login' lets them claim a seat. Only the group's owner may do this. The group to act on. Accepts either a Lightsplit group id or any Lightsplit share link (web, LINE or Telegram) — pass through whatever the user gave you, unchanged.

update_group

Rename a member of a group, or change their permission between 'edit' and 'view'. Renaming only has a visible effect on an UNSEATED placeholder member (is_seated=false). Once a real Lightsplit account claims the seat, that account's own display name is shown everywhere and `name` is ignored. Only the group's owner may do this. Member ids come from get_group; call it first if you do not already have this group's roster. In that roster is_caller marks the member row belonging to the person whose token this is, which is who 'I', 'me' and 'my share' refer to.

update_member

Edit a reminder. Editing REPLACES the reminder wholesale, so pass `what` as the full text you want it to read, not just the change. Get the reminder_id from list_reminders. `currency` and `amount` go together, exactly as in create_reminder: pass both to set (or change) the reminder's price, omit BOTH to leave it a plain reminder with no price.

update_reminder

Use this when the user wants to correct an existing Lightsplit expense, income, or member-to-member payment record. Updates the stored transaction and affected member balances; it does not move real money. Returns the updated transaction and its page links. Get transaction_id from list_transactions and member IDs from get_group. This is a partial update: omit fields the user has not asked to change. Financial edits recalculate the allocations as described below; omitted text, dates, and receipts remain unchanged. Expenses and income: changing amount or currency requires an explicit replacement allocation in splits, or equal_split: true for all active members. Otherwise, omitting both retains the existing allocation. Member-only split entries divide equally among those members; share specifies weights, and amount specifies exact figures. Do not mix weights and exact amounts; every exact entry needs an amount, and they must sum to the transaction total. Payers: omitting payers retains the existing payer identities, not the caller by default. A sole payer's contribution follows the transaction total. If the total changes and there are multiple payers, supply all their new amounts. An explicit payer list replaces the old one; multiple payer amounts must sum to the total. All monetary inputs are positive. Transfers: do not pass splits or equal_split, even when changing amount or currency. A transfer has one payer and one receiver. receiver_member_id changes its receiver and is rejected for expenses and income. Any explicit payer amount must equal the transfer total. Requires edit access to the group. The transaction's type and group cannot be changed. A deactivated member may remain on a transaction they already participated in, but cannot be newly added. WHEN YOU REPORT THE RESULT, give the user the reply's `links` — every non-null one, labelled by channel — so they can open the transaction and check it. Display links on one compact line as Markdown text links, with the exact labels and order: [LINE](<links.line>) · [Telegram](<links.telegram>) · [Web](<links.web>). Replace each placeholder with the exact URL from that reply's `links` object; preserve the entire URL, including all query parameters. Omit null channels and their separators. Render the links normally, not inside a code span or code block. Only show raw URLs if the user explicitly asks for them.

update_transaction