TREK/wiki/Budget-Tracking.md

Costs (Budget Tracking)

Track trip expenses by category, split costs between members, and visualize spending.

Renamed to Costs (v3.3.0, #1464): This feature is now called Costs everywhere in the UI — the planner tab reads Costs and it is listed as Costs in Admin → Addons. Its internal addon id stays budget, which is why the permission is budget_edit and the MCP scopes are budget:read / budget:write.

Where to find it

Open the Costs tab inside the trip planner. The tab is only visible when the Costs addon is enabled.

The tab opens with the same bar as Transports, Bookings, Lists and Files: its name, then the trip's dates with the number of days and the travelers the costs are shared between, and on the right Settle up and Add expense.

Admin: Costs is an addon. Enable it in Admin-Addons.

Currency

Costs is multi-currency (#551). Three settings are involved, and they do different jobs:

• The trip currency (Trip → Edit trip) is the trip's accounting base. Every balance and settle-up is calculated in it.
• Each expense carries its own currency — pick it in the expense modal and enter what the receipt says (a $100 dinner on a rouble trip is 100 USD). It is converted into the trip currency at a rate frozen when you save it, so a settled debt doesn't reopen when the market moves.
• Your display currency (Settings → General) converts what you read — totals, chart, balances — into one currency. It changes nothing that is stored. Left on Trip currency (the default), each trip is shown in its own currency.

165 currencies are supported, with rates from Frankfurter (no API key needed). When an item's currency differs from the display currency, the modal shows the original next to the converted amount ($100.00 ≈ 7 668,71 ₽ · live rate), and the ledger row shows both ($100.00 → 7 668,71 ₽).

Read Currencies for the full picture — how the three interact, what happens when you change a trip's currency, and which currency a public share link is shown in.

Categories

Every expense sits in one of 14 fixed categories. You cannot add, rename, reorder or delete them — you pick one from a row of pills in the expense modal. Each category carries its own icon and colour, which is what the coloured tab on an expense row and the swatches in the sidebar breakdown are showing:

Accommodation, Food & drink, Groceries, Transport, Flights, Activities, Sightseeing, Shopping, Fees & tickets, Health, Tips, Fuel, Parking, Other.

Expenses written before the Costs rework carried free-text categories. Those are matched onto the fixed keys where the stored label is recognisable (a booking saved as Flight reads as Flights, gas as Fuel) and fall back to Other otherwise. Nothing is rewritten in the database, only how the row is displayed.

Expense items

Expenses are listed as a ledger grouped by day, newest day first, with the day's total on the right of each group header. Recorded settle-up payments sit in the same list, so the ledger reads as everything that happened on the trip's money in order. A row shows the category as a coloured tab, the name, the payer chips with what each of them put in, the note, and the total in your display currency — plus a green you lent / red you borrowed chip under the amount when the split leaves you up or down on it. An expense entered in another currency shows the original and the converted amount under the name.

Above the list are a search box, a category filter, a day filter, an All / Paid by me / I'm owed switch and the CSV export button.

Click Add expense, or the pencil beside a row, to open the expense editor:

Field	Notes
What was it for?	The expense name. Required — the dialog will not save without it.
Total amount	What the receipt says. In Ticket mode it is summed from the items instead and cannot be typed.
Currency	The expense's own currency.
Day	Optional expense date. Undated expenses group under No date.
Category	One of the 14 fixed categories.
Who paid?	Who actually put the money down — see Who paid.
Split	How the total is shared out — see Splitting costs.
Note	Free-text note, shown on the row.
Receipts & Invoices	Images and PDFs attached to the expense, several per expense. See Receipts and invoices.

Expenses linked to a booking or a place

An expense can hang off a booking (reservation or transport) or off a place. Both forms carry a Costs block: Create expense saves the record first and then opens the expense editor for it, and on a saved record Link existing expense ties an expense that is already in Costs and belongs nowhere yet. A record can carry several expenses, the flight and the seat upgrade bought for it later. A linked expense is an ordinary expense: it takes a payer, a split, a date and a currency like any other, and it shows up in the settlement.

Every linked expense is listed in the record's Costs block with three actions. The pencil edits it, Unlink, keep the expense lets go of it and leaves it in Costs, and the bin deletes only the expense. The record stands either way. Deleting the booking or the place deletes all of its linked expenses with it.

A booking's price follows its expenses: it shows their sum when they share one currency, otherwise the first one, and it is cleared once nothing is linked any more.

On the phone the booking, transport and place sheets carry the same block. Tap a linked expense to edit it, and Link opens the unlinked expenses right under the buttons, with a search once there are more than a handful.

AI / MCP: update_budget_item takes reservation_id and place_id; null unlinks. An id from another trip is refused. See MCP-Tools-and-Resources.

Receipts and invoices

An expense can carry the receipt or invoice behind it. Attach receipt / invoice in the expense editor opens the file picker for images and PDFs, and several files can go on one expense. They are uploaded when the expense is saved, land in the trip's Files with a link to the expense, and are listed in the editor's Receipts & Invoices block from then on. If the save fails after the upload, the uploaded files are taken back out again; any that could not be removed are reported, so you can delete them in the Files tab.

A row with receipts shows a Receipts chip beside the name, with the count when there is more than one. Click it to open the viewer: it shows one receipt at a time, pages through them with the arrow keys, and offers a download for a PDF.

Remove receipt in the editor only unlinks the file from the expense. The file itself stays on the trip, because editing an expense (budget_edit) does not carry the file permission: to get rid of the file, delete it in the Files tab, which needs file_delete. Uploading a receipt goes through the trip's file upload, so it needs file_upload on top of budget_edit. A file that is also linked to a place or a booking keeps those links. See Documents-and-Files.

Scanning a receipt

With the AI Parsing addon on and a model that reads images (see Model reads images there), a Scan receipt button sits beside Add expense, and on a phone the Costs header carries a scan icon. It is offered to whoever may add expenses.

1. Click Scan receipt. A dialog like the booking import's takes one photo of the receipt (JPG, PNG or WEBP, up to 10 MB; a photo over 40 megapixels or a WEBP over 3.5 MB is refused): drop it on the box, or click the box to pick one or, on a phone, take one. Then click Scan.
2. The dialog closes and the model reads the photo in the background: the background tasks widget shows Reading the receipt…, and you can keep using TREK meanwhile. On a local model running on CPU this takes from a few seconds to a couple of minutes.
3. When it is done, Review expense opens the expense editor pre-filled with what was read: the merchant as the name, the total, the currency and the day. The split stays Equally; switch it to Ticket and the receipt's lines are already listed, each shared by everyone. Discount and free lines are left out, since a Ticket line needs a price. If you may upload files (file_upload), the photo is already in Receipts & Invoices, uploaded when you save like any receipt you attach yourself. Without that permission the editor opens pre-filled all the same, just without the photo.
4. Check everything, pick the category, who paid and the split, and save. Nothing is stored before that.

The scan reads one photo per expense and does not guess the category. A photo nothing could be read from ends on No receipt could be read from this photo., with the reason under it. Scan jobs are kept for about 10 minutes after they finish, like booking imports.

Who paid

Who paid? in the expense editor records who actually put the money down. It is the other half of the settlement maths — the split says who owes for the expense, this says who is out of pocket for it:

• One person paid — pick a member from the dropdown. This is the default.
• Multiple people paid — switch with the link beside the label, include each payer and type what each of them put in. The amounts have to add up to the total; until they do, the dialog reads Payer amounts must add up to … and refuses to save.
• No one paid yet: the first entry in the single-payer dropdown, for an expense you are only planning. The amount still counts toward Total trip spend, but it creates no debt: with nobody out of pocket for it there is nothing to pay anyone back, so it stays out of Balances and out of the settle-up suggestions until you fill in who paid.

An expense with no payer is flagged Unfinished on its row and counted into the Outstanding amount card, which is where to look for the spending that is recorded but not yet settled between anyone.

Splitting costs

Split decides who owes for the expense. Every trip member is listed and can be included or excluded, and there are three modes:

• Equally — Splits the cost equally among selected members. Remainder cents (from rounding errors) are distributed deterministically and rotated using the item ID to ensure everyone is charged equally over the course of the trip.
• Custom — Enter specific custom amounts for each traveler. The sum of the custom splits must balance exactly to the total price.
• Ticket — Build an itemized list of expenses (e.g. Apples: $10, cake: $50, Milk: $40) and assign specific trip participants to split each individual item. Individual shares are calculated cent-perfectly, the total expense price is automatically summed, and the list of itemized splits is saved/restored across edits.

Settlement calculator

Costs works out the minimum number of transfers needed to settle all debts (using a greedy matching algorithm) and keeps the answer in the right-hand column, split across three cards:

• Settle up — the transfer flows: who pays whom and how much. The number of open flows sits in the card header, and each flow has a Settle button that records it as done.
• Balances — net balances: each member's overall surplus or deficit.
• Final budget — what the trip costs each member once every reimbursement is accounted for: expenses paid − net reimbursements − pending reimbursements. Clicking a name opens that breakdown, with the expenses the member paid, the payments already recorded and the transfers still open on their side. The server works those rows out in the currency you are viewing in, at the exchange rate each expense was booked at, so every list adds up to the line above it even before live rates have loaded.

The final budget comes to each member's share of the paid expenses (exact in the trip's own currency; in another display currency, rounding can leave a single figure a cent off while the column still adds up), so recording a payment moves an amount from pending to net reimbursements without changing it. An expense nobody has paid yet stays out of it, as it stays out of the balances.

Settle up in the bar at the top of the tab records every open flow at once. Add payment on the card records a single transfer by hand, for a repayment that did not follow a suggested flow. Recorded payments then appear in the expense ledger as their own rows, with edit and undo beside them.

Balances are always netted in the trip currency and converted to your display currency once, at the end — so they stay stable even when the trip mixes currencies.

A recorded payment carries its own currency too: settling a rouble debt with a euro transfer is normal, so the payment modal has a currency picker, and its rate is frozen when you record it. A payment made in another currency shows both amounts in the ledger ($30.00 → 27,00 €). A payment also carries the day it happened, editable like an expense's date, so a transfer you only get round to recording three days later still lands on the right day; payments recorded before this field existed stay on the day they were recorded.

Costs summary

Four cards sit above the expense list:

• You owe — what you still have to transfer, with the members you owe it to.
• You're owed — the same in the other direction.
• Outstanding amount — the total of the expenses that have no payer yet, and how many of them there are.
• Total trip spend — the grand total in large type, with your share and what you paid underneath.

Below the settle-up and balances cards, the right-hand column ends with By category: spending per category as a ranked list of bars in the category colours. Only categories with spend on them appear, sorted by amount, and the bars are scaled against the biggest category rather than the trip total, so the ranking stays readable.

Exporting

Click Export CSV in the toolbar to download all expenses as a spreadsheet (restored in v3.3.0, #1500). The file is semicolon-delimited with a UTF-8 byte-order mark (so Excel opens it cleanly), rows sorted by date, and is named costs-<trip>.csv. The columns are: Date, Name, Category, Amount, Currency, Amount (), Note — each expense shows both its original amount in its own currency and the converted amount in your display currency.

Permissions

All write operations (adding/editing/deleting expenses and settle-up payments, and an expense's currency) require the budget_edit permission. The trip currency lives on the trip itself, so changing that requires trip_edit instead.

See also

• Currencies
• Admin-Addons
• Reservations-and-Bookings
• Trip-Planner-Overview